Zulip mobile API
The mobile API from Zulip — 6 operation(s) for mobile.
OpenAPI Specification
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.
'