Zulip authentication API
The authentication API from Zulip — 4 operation(s) for authentication.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication API
description: 'Powerful open source group chat
'
contact:
url: https://zulip.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: authentication
paths:
/fetch_api_key:
post:
operationId: fetch-api-key
summary: Fetch an API key (production)
tags:
- authentication
description: "This API endpoint is used by clients such as the Zulip mobile and\nterminal apps to implement password-based authentication. Given the\nuser's Zulip login credentials, it returns a Zulip API key that the client\ncan use to make requests as the user.\n\nThis endpoint is only useful for Zulip servers/organizations with\nEmailAuthBackend or LDAPAuthBackend enabled.\n\nThe Zulip mobile apps also support SSO/social authentication (GitHub\nauth, Google auth, SAML, etc.) that does not use this endpoint. Instead,\nthe mobile apps reuse the web login flow passing the `mobile_flow_otp` in\na webview, and the credentials are returned to the app (encrypted) via a redirect\nto a `zulip://` URL.\n\n!!! warn \"\"\n\n **Note:** If you signed up using passwordless authentication and\n never had a password, you can [reset your password](/help/change-your-password).\n\nSee the [API keys](/api/api-keys) documentation for more details\non how to download an API key manually.\n\nIn a [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),\nsee also [the unauthenticated variant](/api/dev-fetch-api-key).\n"
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
description: '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](/api/get-server-settings) for details.
'
type: string
example: iago@zulip.com
password:
type: string
example: abcd1234
description: 'The user''s Zulip password (or LDAP password, if LDAP authentication is in use).
'
required:
- username
- password
security: []
responses:
'200':
description: 'Valid credentials the client can use to access the Zulip API:
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
/jwt/fetch_api_key:
post:
operationId: jwt-fetch-api-key
summary: Fetch an API key (JWT)
tags:
- authentication
description: "This API endpoint is used by clients to implement JSON Web Token\n(JWT) authentication. Given a JWT identifying a Zulip user, it\nreturns a Zulip API key that the client can use to make requests\nas the user.\n\n!!! warn \"\"\n\n **Note:** This endpoint is only useful for Zulip servers/organizations\n with [JSON web token authentication][prod-jwt-auth] enabled.\n\nSee the [API keys](/api/api-keys) documentation for more details\non how to manage API keys manually.\n\n**Changes**: New in Zulip 7.0 (feature level 160).\n\n[prod-jwt-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#json-web-tokens-jwt\n"
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token:
description: 'A JSON Web Token for the target user.
The token payload must contain a custom `email` claim with the target
user''s email address, e.g., `{"email": "<target user email>"}`.
'
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImhhbWxldEB6dWxpcC5jb20ifQ.EsHxSVt54zPR-ywgPH54TB1FYmrGKsfq7hsQEhp_9w0
include_profile:
type: boolean
default: false
example: false
description: 'Whether to include a `user` object containing the target
user''s profile details in the response.
'
required:
- token
security: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- required:
- api_key
- email
additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
api_key:
type: string
description: 'The API key that can be used to authenticate as the requested user.
'
email:
type: string
description: 'The email address of the user who owns the API key.
'
user:
description: 'Only present if `include_profile` parameter was set to `true`.
A dictionary with data on the target user.
'
allOf:
- $ref: '#/components/schemas/UserBase'
- additionalProperties: false
properties:
user_id: {}
delivery_email:
nullable: true
email: {}
full_name: {}
date_joined: {}
is_active: {}
is_owner: {}
is_admin: {}
is_guest: {}
is_bot: {}
bot_type:
nullable: true
bot_owner_id:
nullable: true
role: {}
timezone: {}
avatar_url:
nullable: true
avatar_version: {}
is_imported_stub: {}
example:
api_key: gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv
email: hamlet@zulip.com
msg: ''
result: success
/dev_fetch_api_key:
post:
operationId: dev-fetch-api-key
summary: Fetch an API key (development only)
tags:
- authentication
description: "For easy testing of mobile apps and other clients and against Zulip\ndevelopment servers, we support fetching a Zulip API key for any user\non the development server without authentication (so that they can\nimplement analogues of the one-click login process available for Zulip\ndevelopment servers on the web).\n\n!!! warn \"\"\n\n **Note:** This endpoint is only available on Zulip development\n servers; for obvious security reasons it will always return an error\n in a Zulip production server.\n"
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
description: 'The email address for the user that owns the API key.
'
type: string
example: iago@zulip.com
required:
- username
security: []
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
/dev_list_users:
get:
operationId: dev-list-users
summary: List users (development only)
tags:
- authentication
description: "Get a list of all, non-bot users in a [Zulip development\nserver](https://zulip.readthedocs.io/en/latest/development/overview.html).\nThis endpoint is used by mobile developers to fetch users for the\ndevelopment login flow.\n\n!!! warn \"\"\n\n **Note:** This endpoint is only available on Zulip development\n servers; for obvious security reasons it will always return an error\n in a Zulip production server.\n"
security: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- type: object
additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
direct_admins:
type: array
description: 'A list of administrators in the development server.
'
items:
type: object
additionalProperties: false
properties:
email:
type: string
description: 'The email of the dev admin user.
'
realm_url:
type: string
description: 'The URL of the dev admin user''s organization.
'
direct_users:
type: array
description: 'A list of non-admin users in the development server.
'
items:
type: object
additionalProperties: false
properties:
email:
type: string
description: 'The email of the dev user.
'
realm_url:
type: string
description: 'The URL of the dev user''s organization.
'
example:
msg: ''
result: success
direct_admins:
- email: iago@zulip.com
realm_url: http://localhost:9991
direct_users:
- email: hamlet@zulip.com
realm_url: http://localhost:9991
components:
schemas:
JsonSuccessBase:
description: '**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`][ignored_params] array.
A typical successful JSON response may look like:
[ignored_params]: /api/rest-error-handling#ignored-parameters
'
allOf:
- $ref: '#/components/schemas/JsonResponseBase'
- required:
- result
- msg
properties:
result:
enum:
- success
msg:
type: string
ignored_parameters_unsupported:
$ref: '#/components/schemas/IgnoredParametersUnsupported'
IgnoredParametersUnsupported:
type: array
items:
type: string
description: 'An array of any parameters sent in the request that are not
supported by the endpoint.
See [error handling](/api/rest-error-handling#ignored-parameters) documentation
for details on this and its change history.
'
JsonResponseBase:
type: object
properties:
result:
type: string
UserBase:
type: object
description: 'A dictionary containing basic data on a given Zulip user.
**Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was
replaced by the `can_manage_billing_group` realm setting.
'
properties:
user_id:
type: integer
description: 'The unique ID of the user.
'
delivery_email:
type: string
nullable: true
description: 'The user''s real email address. This value will be `null` if you cannot
access user''s real email address. For bot users, this field is always
set to the real email of the bot, because bot users always have
`email_address_visibility` set to everyone.
**Changes**: Prior to Zulip 7.0 (feature level 163), this field was
present only when `email_address_visibility` was restricted and you had
access to the user''s real email. As of this feature level, this field
is always present, including the case when `email_address_visibility`
is set to everyone (and therefore not restricted).
'
email:
type: string
description: 'The Zulip API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Zulip API but nothing else.
'
full_name:
type: string
description: 'Full name of the user or bot, used for all display purposes.
'
date_joined:
type: string
description: 'The time when the user joined. For users imported from other
applications and users created via the API, this is set to the
account creation time until the user logs in for the first time,
after which it is updated to that login time.
For imported users, clients can use the `is_imported_stub` flag
to determine how to display this field: when `is_imported_stub`
is `true`, the user has not yet logged in and this value is the
account creation time during import; when `is_imported_stub` is
`false`, this value reflects when the user first logged in.
**Changes**: Starting with Zulip 12.0 (feature level 475),
this field is updated when an imported stub user or a user created
via the API logs in for the first time.
'
is_active:
type: boolean
description: 'A boolean specifying whether the user account has been deactivated.
'
is_owner:
type: boolean
description: 'A boolean specifying whether the user is an organization owner.
If true, `is_admin` will also be true.
**Changes**: New in Zulip 3.0 (feature level 8).
'
is_admin:
type: boolean
description: 'A boolean specifying whether the user is an organization administrator.
'
is_guest:
type: boolean
description: 'A boolean specifying whether the user is a guest user.
'
is_bot:
type: boolean
description: 'A boolean specifying whether the user is a bot or full account.
'
bot_type:
type: integer
nullable: true
description: 'An integer describing the type of bot:
- `null` if the user isn''t a bot.
- `1` for a `Generic` bot.
- `2` for an `Incoming webhook` bot.
- `3` for an `Outgoing webhook` bot.
- `4` for an `Embedded` bot.
'
bot_owner_id:
type: integer
nullable: true
description: 'If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id`
is the user ID of the bot''s owner (usually, whoever created the bot).
Will be `null` for legacy bots that do not have an owner.
**Changes**: New in Zulip 3.0 (feature level 1). In previous
versions, there was a `bot_owner` field containing the email
address of the bot''s owner.
'
role:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: '[Organization-level role](/api/roles-and-permissions) of the user.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
**Changes**: New in Zulip 4.0 (feature level 59).
'
timezone:
type: string
description: 'The IANA identifier of the user''s [profile time zone](/help/change-your-timezone),
which is used primarily to display the user''s local time to other users.
'
avatar_url:
type: string
nullable: true
description: 'URL for the user''s avatar.
Will be `null` if the `client_gravatar`
query parameter was set to `true`, the current user has access to
this user''s real email address, and this user''s avatar is hosted by
the Gravatar provider (i.e. this user has never uploaded an avatar).
**Changes**: Before Zulip 7.0 (feature level 163), access to a
user''s real email address was a realm-level setting. As of this
feature level, `email_address_visibility` is a user setting.
In Zulip 3.0 (feature level 18), if the client has the
`user_avatar_url_field_optional` capability, this will be missing at
the server''s sole discretion.
'
avatar_version:
type: integer
description: 'Version for the user''s avatar. Used for cache-busting requests
for the user''s avatar. Clients generally shouldn''t need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
'
is_imported_stub:
type: boolean
description: 'Indicates whether this user object is a stub account imported from
another chat system. Stub accounts are used to represent the senders
for imported messages. Stub accounts can be converted to regular Zulip
accounts when the user starts using Zulip, preserving that imported
user''s message history.
**Changes**: New in Zulip 12.0 (feature level 433).
'
example: false
is_deleted:
type: boolean
description: 'A boolean specifying whether the user has been permanently
deleted. Deleted users are a subset of deactivated users
(`is_active=false`) who have had their account data removed.
This field is only present when `true`.
**Changes**: New in Zulip 12.0 (feature level 490).
'
ApiKeyResponse:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- required:
- api_key
- email
additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
api_key:
type: string
description: 'The API key that can be used to authenticate as the requested user.
'
email:
type: string
description: 'The email address of the user who owns the API key.
'
user_id:
type: integer
description: 'The unique ID of the user who owns the API key.
**Changes**: New in Zulip 7.0 (feature level 171).
'
example:
api_key: gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv
email: iago@zulip.com
msg: ''
result: success
user_id: 5
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: 'Basic authentication, with the user''s email as the username, and the API
key as the password. The API key can be fetched using the
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
'