Introduction to the REST API
Welcome to Stream's REST API documentation!
The REST documentation is recommended for advanced users that want to write their own API clients.
Have a look below at the official clients, framework integrations, and community-contributed libraries.
Always feel free to get in touch at email@example.com if you have questions.
Are you looking for a ready-made client or framework library?
If you're looking to get started quickly,
official clients are available
You're currently not logged in. Log in so we can add your API key
and other information in the documentation snippets elsewhere on this page.
Base API URL:
The following common GET parameters should be sent for every request:
||The API Key
Note: Every request should also include the appropriate authorization header.
Stream API supports gzip and deflate compression, make sure that your client negotiate compression.
Enabling compression can reduce significantly latency and used bandwidth and it's highly recommended.
Unless specified differently, all POST data must be JSON encoded and all responses are also JSON encoded.
API Keys and Tokens
Every API request to Stream must include: the API Key of the app performing the request and an authentication token generated using the API Key secret.
Token must be a JWT token including a signature generated with the HS256 algorithm.
If you are not familiar with JWT we highly recommend reading more about it here
Libraries to generate JWT are available for most programming languages. The full list is available here.
The authentication token must include the correct claims (also called payload). A token valid for a type of request or for a user_id might not be valid
for another one. Your application should generate the appropriate token; when using client-side auth, each user should have its own unique token.
Sending an authenticated request
All API requests to Stream must include a query parameter called
api_key with the API Key in use.
Once the token is generated correctly it is used to authenticate a request. This is done by setting two HTTP
headers on the request:
Important: Some JWT libraries prefix the generated token with the string "Bearer".
This prefix should be removed before sending the request to Stream.
When dealing with authentication tokens, you should keep in mind that tokens are like passwords.
Never share tokens with untrusted parties.
Requests from a back-end application to Stream Chat API should use Server-Side Authentication to authenticate requests.
JWT usage for server-side authentication
For server-side authentication, the application should send a token that is signed with the API Secret of the Stream app.
This token must not include any claim beside claims defined by JWT specifications (ie. "iat", "exp", ...).
⚠️ When using server-side authentication; there will be no permission checking and you will be able to perform any valid request for any of your user.
You should never share a server-side token with any untrusted party or use it directly on the mobile or web-browser. If your API secret or server-side token gets compromised you should create a new API Key from the dashboard and delete the one that got compromised.
Some endpoints can only used with server-side auth; ie. changing the configuration of your application or perform other actions such as changing users' role.
Here is the server-side token for a fictional application with API Secret "top-secret":
Requests from a front-end application to the Stream Chat API should use Client-Side Authentication to authenticate requests.
JWT usage for client-side authentication
When using client-side auth, you generate different token to each of your user and include their string ID in the
A common approach is to have your users authenticate with your app server-side and to provision a user token so that API calls to Stream can be done on their behalf directly on your mobile/web app.
For security reasons, some API endpoints and some specific actions can be performed only server-side.
User tokens will effectively authenticate the user based on the user_id claim. After that all API calls will be checked for permissions.
More information about permissions is available on Chat documentation.
Here is the user token for user "jack" on a fictional application with API Secret "top-secret":
Anonymous authentication allows you to use a sub-set of Chat's API without generating a user token.
Anonymous authentication works exactly as client-side auth with a couple of exceptions:
- You must not send the Authorization header
- You must send the
stream-auth-type header set to
For security reasons, only a small subset of the API endpoints will be available to anonymous users.
Stream Chat uses Websocket connections to propagate chat events to all connected clients in real-time. Websockets are only used
by Chat API servers to push events to users, you do not need them server-side.
Your Chat application should create a websocket connection per each user and wait until such connection is established before doing any other API call.
Websocket and authentication
Websocket connections must include authentication information; since it is not possible to send HTTP headers or a request body; such information must be included
as query parameters.
Websocket and user data
Websocket connection must include the full information for the current user as well; the API endpoint will ensure that such user exists and will update it if necessary.
Creates a websocket connection for a chat user
JSON encoded payload
the ID for the user (must match JWT's user_id claim)
... additional fields
Websocket hello event
When the websocket connection is created with valid credentials and user payload; you will receive an event which includes fundamental information for later user of chat.
Such message includes:
- Current user's information including unread counts, the list of muted users and banned status
connection_id for this session; you should store this, some API endpoints requires this parameter to be provided
Websocket health-check events
After the websocket connection is correctly established, the client will receive health-checks messages periodically.
Your Chat client should make sure that such health-check event is received not later than 30 seconds ago; if that's not the case
you should close and retry connecting.
Websocket and retries
Unlike REST API calls, websocket connections are long-lived and might get closed due to internet connection errors.
The recommended approach is to monitor internet connection, websocket close and error events and always retry to connect when a network
issue causes the connection to break.
Websocket and precondition errors
If you provide invalid authentication information or invalid data payload, an error message will be sent to the client and the connection will be closed
with a status
1000 Normal Closure immediately after.
You can inspect the error message to gather more information about the failure and use that to decide what to do next. Error messages are JSON encoded and have the same
schema as the ones from REST API endpoints.
When the connection is closed with such status you should not blindly retry to create the connection as it will almost certainly fail again with the same error.
"message":"JWTAuth error: signature is not valid. Make sure the token is created using the secret for API key \"rl5oo8sqdo85\"",
Once the websocket is created, you can move on and subscribe the user to channels either by using the
Query Channels API endpoint or the
Get Or Create Channel.
From that point on, you will receive events related to all channels the user is watching (ie. messages from other users, typing events, mark read events, ...).
Websocket notification events
You should expect the websocket connection to receive events that are not related to channels that the user is watching with the current websocket connection.