Fetch an API key (JWT)

POST https://pijul.zulipchat.com/api/v1/jwt/fetch_api_key

This API endpoint is used by clients to implement JSON Web Token (JWT) authentication. Given a JWT identifying a Zulip user, it returns a Zulip API key that the client can use to make requests as the user.

See the API keys documentation for more details on how to manage API keys manually.

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

Usage examples

curl -sSX POST https://pijul.zulipchat.com/api/v1/jwt/fetch_api_key \
    --data-urlencode token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImhhbWxldEB6dWxpcC5jb20ifQ.EsHxSVt54zPR-ywgPH54TB1FYmrGKsfq7hsQEhp_9w0 \
    --data-urlencode include_profile=false

Parameters

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: object

  Only present if include_profile parameter was set to true.

  A dictionary with data on the target user.

  • user_id: integer

    The unique ID of the user.

  • delivery_email: string | null

    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: string

    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: string

    Full name of the user or bot, used for all display purposes.

  • date_joined: string

    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: boolean

    A boolean specifying whether the user account has been deactivated.

  • is_owner: boolean

    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: boolean

    A boolean specifying whether the user is an organization administrator.

  • is_guest: boolean

    A boolean specifying whether the user is a guest user.

  • is_bot: boolean

    A boolean specifying whether the user is a bot or full account.

  • bot_type: integer | null

    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: integer | null

    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: integer

    Organization-level role 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: string

    The IANA identifier of the user's profile time zone, which is used primarily to display the user's local time to other users.

  • avatar_url: string | null

    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: integer

    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: boolean

    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 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": "hamlet@zulip.com",
    "msg": "",
    "result": "success"
}