Skip to main content
Token authentication uses a trusted device with an API key to issue time-limited tokens to untrusted clients. Tokens have a limited set of access rights, known as capabilities, and can have a specific identity using a clientId. Token authentication is the recommended authentication method to use client-side for the following reasons:
  • Tokens ensure that an Ably API key isn’t exposed in client applications.
  • Tokens are short-lived so there is only a short period of time during which a compromised token can be used.
  • Tokens provide more fine-grained access control, which also limits the area of exposure a compromised token can access.
  • Tokens support functionality not available with Basic auth, such as user claims.

​
How token authentication works

  1. Your client calls authUrl or authCallback to request a token from your server.
  2. Your server validates the client and returns a token (JWT, TokenRequest, or Ably Token).
  3. The client uses this token to authenticate with Ably.
  4. Tokens are short-lived and expire after a set period.
  5. The client SDK automatically requests a new token before expiry, ensuring uninterrupted connectivity.

​
Using authCallback

The authCallback is a function that the SDK calls when it needs a token. Your callback should request a token from your server and return it:

​
Using authUrl

The authUrl is a URL that the SDK calls to obtain a token. The SDK will make an HTTP request to this URL and expect a token in the response:

​
Token types

Ably supports two token formats: JWTs are the recommended approach for most applications:
  • No Ably SDK required on your server. Any JWT library works.
  • Supports channel-scoped claims for trusted metadata
  • Supports per-connection rate limits
  • Stateless and ideal for serverless environments

​
Ably Tokens

Ably tokens are an alternative mechanism:
  • TokenRequest: Server creates a signed request locally, client exchanges it with Ably
  • Ably Token (direct): Server requests token from Ably, passes it to client
Use Ably Tokens when:
  • Your capability list is very large (JWTs must fit within HTTP header limits)
  • You need to keep capabilities confidential (clients can decode JWTs)

​
Token refresh

One of the important benefits of using an Ably SDK is that automatic token refresh is handled for you. When you provide either an authUrl or an authCallback, the SDK automatically:
  1. Calls your auth endpoint when connecting
  2. Requests a new token before the current token expires
  3. Maintains the connection seamlessly during refresh

​
Token TTL limits

Ably enforces maximum TTL (time-to-live) limits:
  • Access tokens: Maximum TTL of 24 hours.
  • Device tokens (for push notifications): Maximum TTL of 5 years.
  • Revocable tokens: Maximum TTL of 1 hour. A token is revocable if token revocation has been enabled for the API key used to issue it.

​
Server-side token generation

Your server should generate tokens using the Ably SDK. Here’s an example:

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us