Get server settings

GET https://io.phoebus.de/api/v1/server_settings

Fetch global settings for a Zulip server.

Note: this endpoint does not require any authentication at all, and you can use it to check:

• If this is a Zulip server, and if so, what version of Zulip it's running.
• What a Zulip client (e.g. a mobile app or zulip-terminal) needs to know in order to display a login prompt for the server (e.g. what authentication methods are available).

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Fetch the settings for this server.
result = client.get_server_settings()
print(result)

curl -sSX GET -G https://io.phoebus.de/api/v1/server_settings \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

Parameters

This endpoint does not accept any parameters.

Response

Return values

• authentication_methods: object

  Each key-value pair in the object indicates whether the authentication method is enabled on this server.

  Changes: Deprecated in Zulip 2.1.0, in favor of the more expressive external_authentication_methods.

  • password: boolean

    Whether the user can authenticate using password.

  • dev: boolean

    Whether the user can authenticate using development API key.

  • email: boolean

    Whether the user can authenticate using email.

  • ldap: boolean

    Whether the user can authenticate using LDAP.

  • remoteuser: boolean

    Whether the user can authenticate using REMOTE_USER.

  • github: boolean

    Whether the user can authenticate using their GitHub account.

  • azuread: boolean

    Whether the user can authenticate using their Azure Active Directory account.

  • gitlab: boolean

    Whether the user can authenticate using their GitLab account.

    Changes: New in Zulip 3.0 (feature level 1).

  • apple: boolean

    Whether the user can authenticate using their Apple account.

  • google: boolean

    Whether the user can authenticate using their Google account.

  • saml: boolean

    Whether the user can authenticate using SAML.

  • openid connect: boolean

    Whether the user can authenticate using OpenID Connect.

• external_authentication_methods: (object)[]

  A list of dictionaries describing the available external authentication methods (E.g. Google, GitHub, or SAML) enabled for this organization.

  The list is sorted in the order in which these authentication methods should be displayed.

  Changes: New in Zulip 2.1.0.

  • name: string

    A unique, table, machine-readable name for the authentication method, intended to be used by clients with special behavior for specific authentication methods to correctly identify the method.

  • display_name: string

    Display name of the authentication method, to be used in all buttons for the authentication method.

  • display_icon: string | null

    URL for an image to be displayed as an icon in all buttons for the external authentication method.

    When null, no icon should be displayed.

  • login_url: string

    URL to be used to initiate authentication using this method.

  • signup_url: string

    URL to be used to initiate account registration using this method.

• zulip_feature_level: integer

  An integer indicating what features are available on the server. The feature level increases monotonically; a value of N means the server supports all API features introduced before feature level N. This is designed to provide a simple way for client apps to decide whether the server supports a given feature or API change. See the changelog for details on what each feature level means.

  Changes: New in Zulip 3.0 (feature level 1). We recommend using an implied value of 0 for Zulip servers that do not send this field.

• zulip_version: string

  The server's version number. This is often a release version number, like 2.1.7. But for a server running a version from Git, it will be a Git reference to the commit, like 5.0-dev-1650-gc3fd37755f.

• zulip_merge_base: string

  The git merge-base between zulip_version and official branches in the public Zulip server and web app repository, in the same format as zulip_version. This will equal zulip_version if the server is not running a fork of the Zulip server.

  This will be "" if unavailable.

  Changes: New in Zulip 5.0 (feature level 88).

• push_notifications_enabled: boolean

  Whether mobile/push notifications are configured.

• is_incompatible: boolean

  Whether the Zulip client that has sent a request to this endpoint is deemed incompatible with the server.

• email_auth_enabled: boolean

  Setting for allowing users authenticate with an email-password combination.

• require_email_format_usernames: boolean

  Whether all valid usernames for authentication to this organization will be email addresses. This is important for clients to know whether to do client side validation of email address format in a login prompt.

  This value will be false if the server has LDAP authentication enabled with a username and password combination.

• realm_uri: string

  The organization's canonical URL. Alias of realm_url.

  Changes: Deprecated in Zulip 9.0 (feature level 257). The term "URI" is deprecated in web standards.

• realm_url: string

  The organization's canonical URL.

  Changes: New in Zulip 9.0 (feature level 257), replacing the deprecated realm_uri.

• realm_name: string

  The organization's name (for display purposes).

• realm_icon: string

  The URL for the organization's logo formatted as a square image, used for identifying the organization in small locations in the mobile and desktop apps.

• realm_description: string

  HTML description of the organization, as configured by the organization profile.

• realm_web_public_access_enabled: boolean

  Whether the organization has enabled the creation of web-public channels and at least one web-public channel on the server currently exists. Clients that support viewing content in web-public channels without an account can use this to determine whether to offer that feature on the login page for an organization.

  Changes: New in Zulip 5.0 (feature level 116).

Please note that not all of these attributes are guaranteed to appear in a response, for two reasons:

• This endpoint has evolved over time, so responses from older Zulip servers might be missing some keys (in which case a client should assume the appropriate default).
• If a /server_settings request is made to the root domain of a multi-subdomain server, like the root domain of zulip.com, the settings that are realm-specific are not known and thus not provided.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "authentication_methods": {
        "azuread": false,
        "dev": true,
        "email": true,
        "github": true,
        "google": true,
        "ldap": false,
        "password": true,
        "remoteuser": false,
        "saml": true
    },
    "email_auth_enabled": true,
    "external_authentication_methods": [
        {
            "display_icon": null,
            "display_name": "SAML",
            "login_url": "/accounts/login/social/saml/idp_name",
            "name": "saml:idp_name",
            "signup_url": "/accounts/register/social/saml/idp_name"
        },
        {
            "display_icon": "/static/images/authentication_backends/googl_e-icon.png",
            "display_name": "Google",
            "login_url": "/accounts/login/social/google",
            "name": "google",
            "signup_url": "/accounts/register/social/google"
        },
        {
            "display_icon": "/static/images/authentication_backends/github-icon.png",
            "display_name": "GitHub",
            "login_url": "/accounts/login/social/github",
            "name": "github",
            "signup_url": "/accounts/register/social/github"
        }
    ],
    "is_incompatible": false,
    "msg": "",
    "push_notifications_enabled": false,
    "realm_description": "<p>The Zulip development environment default organization.  It's great for testing!</p>",
    "realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
    "realm_name": "Zulip Dev",
    "realm_uri": "http://localhost:9991",
    "realm_url": "http://localhost:9991",
    "realm_web_public_access_enabled": false,
    "require_email_format_usernames": true,
    "result": "success",
    "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
    "zulip_version": "5.0-dev-1650-gc3fd37755f"
}