openapi: 3.0.1
info:
  version: 1.0.0
  title: Zulip REST authentication mobile 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: mobile
paths:
  /mobile_push/test_notification:
    post:
      deprecated: true
      operationId: test-notify
      summary: Send a test notification to mobile device(s)
      tags:
      - mobile
      description: 'Trigger sending a test push notification to the user''s

        selected mobile device or all of their mobile devices.


        **Changes**: Deprecated in Zulip 11.0 (feature level 420).

        Clients connecting to newer servers and with E2EE push

        notifications support should use the

        [Send an E2EE test notification to mobile device(s)](/api/e2ee-test-notify)

        endpoint, as this endpoint will be removed in a future release.


        Starting with Zulip 8.0 (feature level 234), test

        notifications sent via this endpoint use `test` rather than

        `test-by-device-token` in the `event` field. Also, as of this

        feature level, all mobile push notifications now include a

        `realm_name` field.


        New in Zulip 8.0 (feature level 217).

        '
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  description: 'The push token for the device to which to send the test notification.


                    If this parameter is not submitted, the test notification will be sent

                    to all of the user''s devices registered on the server.


                    A mobile client should pass this parameter, to avoid triggering a test

                    notification for other clients.

                    '
                  type: string
                  example: '111222'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccess'
        '400':
          description: 'Bad request.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidPushDeviceTokenError'
                - $ref: '#/components/schemas/InvalidRemotePushDeviceTokenError'
  /mobile_push/e2ee/test_notification:
    post:
      operationId: e2ee-test-notify
      summary: Send an E2EE test notification to mobile device(s)
      tags:
      - mobile
      description: 'Trigger sending an end-to-end encrypted (E2EE) test push notification

        to the user''s selected mobile device or all of their mobile devices.


        **Changes**: New in Zulip 11.0 (feature level 420).

        '
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                device_id:
                  description: 'The ID for the device to which to send the test notification.


                    If this parameter is not submitted, the E2EE test notification will

                    be sent to all of the user''s devices registered on the server.


                    A mobile client should pass this parameter, to avoid triggering a test

                    notification for other clients.


                    See [`POST /register_client_device`](/api/register-client-device)

                    for details on device ID.


                    **Changes**: New in Zulip 12.0 (feature level 468).


                    Previously, `push_account_id` was used.

                    '
                  type: integer
                  example: 1144
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccess'
        '400':
          description: 'Bad request.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NoActivePushDeviceError'
        '403':
          description: 'Forbidden.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PushNotificationAdminActionRequiredError'
        '502':
          description: 'Bad gateway.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/FailedToConnectBouncerError'
                - $ref: '#/components/schemas/InternalBouncerServerError'
  /mobile_push/register:
    post:
      operationId: register-push-device
      summary: Register E2EE push device
      tags:
      - mobile
      description: 'Register a device to receive end-to-end encrypted mobile push notifications,

        or update such a registration.


        To perform an initial registration, clients must provide both the

        push key fields (`push_key` and `push_key_id`) and the token fields

        (`token_kind`, `token_id`, `bouncer_public_key`, and `encrypted_push_registration`).


        Once registered, clients should use this endpoint to rotate `push_key` or

        FCM/APNs provided token:


        - **Rotate push key**: Provide only the push key fields.

        - **Rotate token**: Provide only the token fields.


        On a successful registration, the server automatically removes

        any legacy push device registration with a matching token for

        the user. For self-hosted servers, if removing the legacy

        registration from the push notification bouncer fails (e.g.,

        due to a network error), legacy notifications to that token

        will continue until all of the user''s legacy registrations

        have been removed from the local server, at which point the

        server will stop sending legacy notification requests to the

        bouncer entirely.


        **Changes**: In Zulip 12.0 (feature level 483),

        the server began automatically removing legacy registrations

        with a matching token on successful E2EE registration.


        In Zulip 12.0 (feature level 468), the endpoint was significantly

        redesigned to support rotation of `push_key` and token provided by FCM/APNs.


        New in Zulip 11.0 (feature level 406).

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                device_id:
                  description: 'The ID of the device to configure for push notifications.


                    See [`POST /register_client_device`](/api/register-client-device)

                    for how to obtain a device ID.

                    '
                  type: integer
                  example: 1
                push_key_id:
                  description: 'A random unsigned 32-bit integer generated by the client as an identifier

                    for `push_key`. It will be included in mobile push notifications

                    along with encrypted payloads to identify the `push_key` to decrypt.

                    '
                  type: integer
                  example: 2408
                push_key:
                  description: "Key that the client would like the server to use to encrypt notifications,\nencoded with Base64.\n\nThe key is a byte sequence beginning with a single byte that encodes which\ncryptosystem to use, followed by the key to use for that cryptosystem.\nThis byte sequence is encoded using standard Base64 encoding as defined in RFC 4648.\n\nThe client should avoid sharing the key anywhere else: in particular it should\ngenerate a fresh key for each server, and to the extent possible keep the key\nout of any backups of the client's data.\n\nSupported cryptosystems are:\n\n- `0x31`: LibSodium's [SecretBox][libsodium-secretbox] symmetric key encryption\n  system. Keys are 32 bytes, which the server will use with libsodium's\n  `crypto_secretbox_easy`. See the [NaCl documentation][nacl-secretbox], which\n  details how this system uses `XSalsa20` and `Poly1305` to provide authenticated\n  encryption.\n\n[libsodium-secretbox]: https://libsodium.gitbook.io/doc/secret-key_cryptography/secretbox\n[nacl-secretbox]: https://nacl.cr.yp.to/secretbox.html\n\n**Changes**: New in Zulip 12.0 (feature level 432). This replaced the\n`push_public_key` parameter which had a prototype asymmetric cryptosystem, and\ndid not have a natural way to support multiple cryptosystems.\n"
                  type: string
                  example: MTaUDJDMWypQ1WufZ1NRTHSSvgYtXh1qVNSjN3aBiEFt
                token_kind:
                  description: 'Whether the token was generated by FCM or APNs.

                    '
                  type: string
                  enum:
                  - fcm
                  - apns
                  example: fcm
                token_id:
                  description: 'Identifier for the FCM/APNs provided token to the device,

                    produced by taking the first 8 bytes of the SHA-256 hash of

                    the token, then encoding those bytes using standard Base64 encoding

                    as defined in RFC 4648.

                    '
                  type: string
                  example: hGsEWGmyyfI=
                bouncer_public_key:
                  description: 'Which of the bouncer''s public keys the client used to encrypt the

                    `PushRegistration` dictionary.


                    When the bouncer rotates the key, a new asymmetric key pair is created,

                    and the new public key is baked into a new client release. Because

                    the bouncer routinely rotates key, this field clarifies which

                    public key the client is using.


                    The public key is encoded using standard Base64 encoding as defined

                    in RFC 4648.

                    '
                  type: string
                  example: bouncer-public-key
                encrypted_push_registration:
                  description: 'Ciphertext generated by encrypting a `PushRegistration` dictionary

                    using the `bouncer_public_key`, encoded using a RFC 4648 standard

                    base64 encoder.


                    The `PushRegistration` dictionary contains the fields `token`,

                    `token_kind`, `timestamp`, and (for iOS devices) `ios_app_id`.

                    The dictionary is JSON-encoded before encryption.

                    '
                  type: string
                  example: encrypted-push-registration-data
              required:
              - device_id
      responses:
        '200':
          $ref: '#/components/responses/SimpleSuccess'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - example:
                    result: error
                    msg: Server is not configured to use push notification service.
                    code: PUSH_SERVICE_NOT_CONFIGURED
                  description: 'Error when the server is not configured to use push notification service:

                    '
  /remotes/push/e2ee/register:
    post:
      operationId: register-remote-push-device
      summary: Register E2EE push device to bouncer
      tags:
      - mobile
      description: 'Register a push device to bouncer to receive end-to-end encrypted

        mobile push notifications.


        Self-hosted servers use this endpoint to asynchronously register

        a push device to the bouncer server after receiving a request from

        the mobile client to [register E2EE push device](/api/register-push-device).


        It is not meant to be used by mobile clients directly.


        **Changes**: New in Zulip 11.0 (feature level 406).

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                realm_uuid:
                  description: 'The UUID of the realm to which the push device

                    being registered belongs.

                    '
                  type: string
                  example: 9aa61d0b-8ce5-488d-8e9e-fedc346e6836
                token_id:
                  description: 'The `token_id` value provided by the mobile client

                    to [register E2EE push device](/api/register-push-device).


                    **Changes**: New in Zulip 12.0 (feature level 468),

                    replacing `push_account_id`.

                    '
                  type: string
                  example: +wKIhyAx/Eg=
                encrypted_push_registration:
                  description: 'The `encrypted_push_registration` value provided by the mobile client

                    to [register E2EE push device](/api/register-push-device).

                    '
                  type: string
                  example: encrypted-push-registration-data
                bouncer_public_key:
                  description: 'The `bouncer_public_key` value provided by the mobile client

                    to [register E2EE push device](/api/register-push-device).

                    '
                  type: string
                  example: bouncer-public-key
              required:
              - realm_uuid
              - token_id
              - encrypted_push_registration
              - bouncer_public_key
      responses:
        '200':
          $ref: '#/components/responses/SimpleSuccess'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                oneOf:
                - allOf:
                  - $ref: '#/components/schemas/CodedError'
                  - example:
                      code: INVALID_BOUNCER_PUBLIC_KEY
                      msg: Invalid bouncer_public_key
                      result: error
                    description: 'An example JSON response for when the given `bouncer_public_key` is invalid:

                      '
                - allOf:
                  - $ref: '#/components/schemas/CodedError'
                  - example:
                      code: REQUEST_EXPIRED
                      msg: Request expired
                      result: error
                    description: 'An example JSON response for when the given `encrypted_push_registration` is stale:

                      '
                - allOf:
                  - $ref: '#/components/schemas/CodedError'
                  - example:
                      code: BAD_REQUEST
                      msg: Invalid encrypted_push_registration
                      result: error
                    description: 'An example JSON response for when either the bouncer fails to decrypt

                      the given `encrypted_push_registration` or the decrypted data is invalid:

                      '
        '403':
          description: 'Forbidden.

            '
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - example:
                    code: MISSING_REMOTE_REALM
                    msg: Organization not registered
                    result: error
                  description: 'An example JSON response for when no realm is registered for

                    the authenticated server on the bouncer for the given `realm_uuid`:

                    '
  /register_client_device:
    post:
      operationId: register-client-device
      summary: Register a logged-in device
      tags:
      - mobile
      description: 'Logged-in mobile devices use this endpoint as an initial step to

        register themselves, before registering for E2EE push notifications.


        This endpoint is currently not useful for clients other than mobile.


        **Changes**: New in Zulip 12.0 (feature level 468).

        '
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccessBase'
                - additionalProperties: false
                  required:
                  - device_id
                  properties:
                    result: {}
                    msg: {}
                    ignored_parameters_unsupported: {}
                    device_id:
                      type: integer
                      description: 'The ID of the newly registered device.

                        '
                  example:
                    msg: ''
                    device_id: 2
                    result: success
  /remove_client_device:
    post:
      operationId: remove-client-device
      summary: Remove a registered device
      tags:
      - mobile
      description: 'Mobile devices use this endpoint to remove their device record

        registered using [`POST /register_client_device`](/api/register-client-device)

        when the user logs out.


        This endpoint is currently not useful for clients other than mobile.


        **Changes**: New in Zulip 12.0 (feature level 470).

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                device_id:
                  description: 'The ID of the device to remove.

                    '
                  type: integer
                  example: 2
              required:
              - device_id
      responses:
        '200':
          $ref: '#/components/responses/SimpleSuccess'
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'
    JsonSuccess:
      allOf:
      - $ref: '#/components/schemas/JsonSuccessBase'
      - additionalProperties: false
        properties:
          result: {}
          msg: {}
          ignored_parameters_unsupported: {}
        example:
          msg: ''
          result: success
    PushNotificationAdminActionRequiredError:
      allOf:
      - $ref: '#/components/schemas/CodedError'
      - example:
          code: ADMIN_ACTION_REQUIRED
          msg: Push notification configuration issue on server, contact the server administrator or retry later.
          result: error
        description: '## Admin action required


          A typical failed JSON response for when there is a push notification

          configuration issue on the server, such as invalid credentials,

          an expired plan, or an unregistered organization. Admin action is required.

          '
    InternalBouncerServerError:
      allOf:
      - $ref: '#/components/schemas/CodedError'
      - example:
          code: INTERNAL_SERVER_ERROR_ON_BOUNCER
          msg: Internal server error on Zulip push notification service, retry later.
          result: error
        description: '## Internal bouncer server error


          A typical failed JSON response for when a 5xx error occurs on the bouncer server.

          '
    InvalidRemotePushDeviceTokenError:
      allOf:
      - $ref: '#/components/schemas/CodedError'
      - example:
          code: INVALID_REMOTE_PUSH_DEVICE_TOKEN
          msg: Device not recognized by the push bouncer
          result: error
        description: '## Invalid push device token


          A typical failed JSON response for when the push device token is not recognized

          by the push notification bouncer:

          '
    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
    InvalidPushDeviceTokenError:
      allOf:
      - $ref: '#/components/schemas/CodedError'
      - example:
          code: INVALID_PUSH_DEVICE_TOKEN
          msg: Device not recognized
          result: error
        description: '## Invalid push device token


          A typical failed JSON response for when the push device token is not

          recognized by the Zulip server:

          '
    FailedToConnectBouncerError:
      allOf:
      - $ref: '#/components/schemas/CodedError'
      - example:
          code: FAILED_TO_CONNECT_BOUNCER
          msg: Network error while connecting to Zulip push notification service.
          result: error
        description: '## Failed to connect bouncer


          A typical failed JSON response for when a network error occurs

          while the server attempts to connect to the bouncer server.

          '
    CodedError:
      allOf:
      - $ref: '#/components/schemas/CodedErrorBase'
      - additionalProperties: false
        properties:
          result: {}
          msg: {}
          code: {}
    NoActivePushDeviceError:
      allOf:
      - $ref: '#/components/schemas/CodedError'
      - example:
          code: NO_ACTIVE_PUSH_DEVICE
          msg: No active registered push device
          result: error
        description: '## No active push device


          A typical failed JSON response for when no registered device is available

          for the user (and `push_account_id`) to receive a push notification.

          '
    CodedErrorBase:
      allOf:
      - $ref: '#/components/schemas/JsonResponseBase'
      - required:
        - result
        - msg
        - code
        properties:
          result:
            enum:
            - error
          msg:
            type: string
          code:
            type: string
            description: 'A string that identifies the error.

              '
  responses:
    SimpleSuccess:
      description: Success.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonSuccess'
  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.

        '