Fetch an API key (production)
POST https://chat.ocaml.pro/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://chat.ocaml.pro/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
}