Tokens & Authentication

LAST EDIT Apr 26 2021



Tokens are used to authenticate the user. Typically, you send this token from your backend to the client-side when a user registers or logs in.

You can generate tokens server side with the following syntax:

By default, user tokens are valid indefinitely. You can set an expiration to tokens by passing it as the second parameter. The expiration should contain the number of seconds since Unix epoch (00:00:00 UTC on 1 January 1970).

Development Tokens


For development applications, it is possible to disable token authentication and use client-side generated tokens. Disabling auth checks is not suitable for a production application and should only be done for proofs-of-concept and applications in the early development stage. To enable development tokens, you need to change your application configuration - On the Dashboard, Go to App -> Chat -> Chat Overview -> Disable Auth Checks (Enable this option so creating development tokens is possible)

The above code used the connectUser call. The connectUser call is the most convenient option when your app has authenticated users. Alternatively, you can use setGuestUser if you want to allow users to chat with a guest account or the connectAnonymousUser if you want to allow anonymous users to watch the chat.

Token Expiration


If you're using tokens with an expiration date you'll want to update tokens as soon as a token exception occurs. Our React, RN, iOS, Android and Flutter libraries have built-in support for this.

Here is the regular flow to handle tokens with expiration with a token provider:

  1. Chat is initialized using the API Key and the token provider

  2. The Chat client will use the token provider to fetch the token when connectUser is called

  3. When the token expires, the API will return a specific Authentication error code

  4. The client will pause API requests and use the token provider to obtain a fresh token

  5. The token provider returns a new token (ie. from your backend)

  6. Chat client replaces the old token with the new one and use it for all waiting and future API calls

A token provider is a function or class that you implement and that is responsible for requesting a new token from your own login infrastructure.

The most common token provider implementation does an HTTP call to your backend with the ID of the user as well as a valid session id or secret needed to authenticate them.

Guest Users


Guest sessions can be created client-side and do not require any server-side authentication.

Guest users have a limited set of permissions. You can read more about how to configure permissions here. You can create a guest user session by using setGuestUser instead of connectUser.

The user object schema is the same as the one described in the Setting the user portion of the docs.

Anonymous Users


If a user is not logged in, you can call the connectAnonymousUser method. While you’re anonymous, you can’t do much, but for the livestream channel type, you’re still allowed to read the chat conversation.

Logging Out & Switching Users


To disconnect a user (say that you’re for instance logging out and logging in as someone new) you can call the disconnectUser method and repeat the connectUser call as someone else: