Ably Tokens

Ably tokens are an alternative mechanism for authenticating with Ably.

They are not generated by a client but are issued by the Ably service via a /requestToken endpoint; a client generates a signed Token Request and this is exchanged for a token by the Ably service. Generally, integrating an application to use Ably tokens is more involved as Ably tokens also do not support all of the functionality available to JWTs.

JWTs are the recommended mechanism for authenticating with Ably, however there are still some circumstances where the use of Ably tokens may be preferred:

• Your capability list is too large and exceeds JWT size limits (JWTs must fit within HTTP header limits, typically around 8 KB).
• You need to keep your capability list confidential, as JWTs can be decoded by clients.

Choosing between TokenRequest and Ably Token (direct)

Ably tokens are always issued by the Ably service via a token request. The two flows differ in who performs the request and what is passed to the client:

Server passes TokenRequest to client

Your server creates a signed TokenRequest using the Ably SDK. The client then exchanges this with Ably to get an actual token.

1. Your server creates a signed TokenRequest using the Ably SDK (no Ably API call needed).
2. Your server sends the TokenRequest to the client.
3. The client sends the TokenRequest to Ably, which returns an Ably Token.

Key characteristics:

• Server never contacts Ably. It just creates and signs the request locally.
• Client makes the token request to Ably.

Server passes token to client

Your server requests a token directly from Ably and passes the ready-to-use token to the client.

1. Your server requests an Ably Token from Ably using the Ably SDK.
2. Ably returns the Ably Token to your server.
3. Your server sends the Ably Token to the client.
4. The client uses the Ably Token directly (no additional Ably contact needed).

Key characteristics:

• Server contacts Ably to get the token
• Client saves one round trip (doesn't need to contact Ably)
• Trade-off: server must communicate with Ably for each token

TokenRequest

Using an Ably SDK, a TokenRequest is generated from your server and returned to the client-side SDK instance. The client-side SDK instance then uses the TokenRequest to request an Ably Token from Ably.

Key characteristics:

• A TokenRequest can be generated by your servers without communicating with Ably.
• Your secret API key is never shared with Ably or your clients.
• A TokenRequest cannot be tampered with due to being signed, must be used soon after creation, and can only be used once.

Server examples

const ably = new Ably.Rest({ key: 'demokey:*****' });
const tokenRequest = await ably.auth.createTokenRequest({ clientId: '[email protected]' });
// Return tokenRequest to client as JSON

Client usage

The client SDK automatically handles TokenRequests returned from your auth endpoint:

const realtime = new Ably.Realtime({
  authCallback: async (tokenParams, callback) => {
    try {
      const response = await fetch('/api/ably-token');
      const tokenRequest = await response.json();
      callback(null, tokenRequest);
    } catch (error) {
      callback(error, null);
    }
  },
});

Ably Token (direct)

Using an Ably SDK, an Ably Token is requested by your server from Ably and then passed to the client. The client uses this token directly to authenticate. The client does not need to make an additional round trip to Ably.

Having the server obtain the token directly is generally more reliable. It minimizes the time delay between creation of the TokenRequest and requesting the token, and eliminates reliance on the accuracy of the clock in the client.

The main reason to prefer having the client request the token (via a TokenRequest) is scalability: if the server obtains the token directly, it must make a request to Ably for each client token, and this scales with the rate of token requests from clients.

Server examples

const ably = new Ably.Rest({ key: 'demokey:*****' });
const tokenDetails = await ably.auth.requestToken({ clientId: '[email protected]' });
// Return tokenDetails.token to client

Client usage

The client code for Ably Token direct is the same as for TokenRequest — the SDK handles the token transparently:

const realtime = new Ably.Realtime({
  authCallback: async (tokenParams, callback) => {
    try {
      const response = await fetch('/api/ably-token');
      const tokenDetails = await response.json();
      callback(null, tokenDetails);
    } catch (error) {
      callback(error, null);
    }
  },
});

For embedded token JWTs, where you embed an Ably Token within an outer JWT used by your existing authentication system, see Embedded Token JWT.