Fetch an API key (production)

POST https://cs-e4160-spring-2023.zulip.aalto.fi/api/v1/fetch_api_key

This API endpoint is used by clients such as the Zulip mobile and terminal apps to implement password-based authentication. Given the user's Zulip login credentials, it returns a Zulip API key that the client can use to make requests as the user.

This endpoint is only useful for Zulip servers/organizations with EmailAuthBackend or LDAPAuthBackend enabled.

The Zulip mobile apps also support SSO/social authentication (GitHub auth, Google auth, SAML, etc.) that does not use this endpoint. Instead, the mobile apps reuse the web login flow passing the mobile_flow_otp in a webview, and the credentials are returned to the app (encrypted) via a redirect to a zulip:// URL.

Note: If you signed up using passwordless authentication and never had a password, you can reset your password.

See the API keys documentation for more details on how to download an API key manually.

In a Zulip development environment, see also the unauthenticated variant.

Usage examples

curl -sSX POST https://cs-e4160-spring-2023.zulip.aalto.fi/api/v1/fetch_api_key \
    --data-urlencode username=iago@zulip.com \
    --data-urlencode password=abcd1234

Parameters

username string required

Example: "iago@zulip.com"

The username to be used for authentication (typically, the email address, but depending on configuration, it could be an LDAP username).

See the require_email_format_usernames parameter documented in GET /server_settings for details.


password string required

Example: "abcd1234"

The user's Zulip password (or LDAP password, if LDAP authentication is in use).


Response

Return values

  • api_key: string

    The API key that can be used to authenticate as the requested user.

  • email: string

    The email address of the user who owns the API key.

  • user_id: integer

    The unique ID of the user who owns the API key.

    Changes: New in Zulip 7.0 (feature level 171).

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:

{
    "api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv",
    "email": "iago@zulip.com",
    "msg": "",
    "result": "success",
    "user_id": 5
}