Get server settings
GET https://thehowedepot.com/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://thehowedepot.com/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_verson
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 enabled.
-
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.
-
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 streams and
at least one web-public stream on the server currently
exists. Clients that support viewing content
in web-public streams 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)
A typical successful JSON response for a single-organization server 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_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"
}