Chat authentication

Chat authentication is handled by the underlying Pub/Sub SDK. You authenticate an Ably Realtime client, then pass that authenticated client into ChatClient.

Authentication flow

1. Your auth server authenticates the user.
2. Your auth server issues an Ably-compatible token (JWT format is recommended for most apps).
3. The client SDK fetches tokens with authCallback and refreshes them automatically before expiry.
4. The authenticated Pub/Sub client is passed into ChatClient.

Server setup

Create an endpoint that validates user-provided credentials and returns JWTs with the appropriate Chat capabilities:

// Server-side JWT with Chat capabilities
import jwt from 'jsonwebtoken';

const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');

const ablyJwt = jwt.sign(
  {
    'x-ably-capability': JSON.stringify({
      // Only allow access to a specific room
      'your-room': ['publish', 'subscribe', 'presence', 'history'],
    }),
    'x-ably-clientId': userId,
  },
  keySecret,
  { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
);

Client setup

import * as Ably from 'ably';
import { ChatClient } from '@ably/chat';

const realtimeClient = new Ably.Realtime({
  authCallback: async (tokenParams, callback) => {
    try {
      const response = await fetch('/api/ably-token', { credentials: 'include' });
      if (!response.ok) throw new Error('Auth failed');
      const jwt = await response.text();
      callback(null, jwt);
    } catch (error) {
      callback(error, null);
    }
  },
});

const chatClient = new ChatClient(realtimeClient);

In each example, the authenticated Pub/Sub client is passed into ChatClient and Chat uses that connection for authentication and token renewal.

Chat capabilities

Capabilities are permissions that control what operations a client can perform. When you create a token for a Chat user, you specify which capabilities they have. Each Chat feature requires specific capabilities:

Room-scoped capabilities

You can scope capabilities to specific rooms, a namespace of rooms, or all rooms:

• my-chat-room - a specific room
• dms:* - all rooms in the dms: namespace
• * - all chat rooms

Token lifecycle and permission updates

• With authCallback or authUrl, token refresh is automatic and handled by the SDK.
• To change a user's capabilities during an active session, issue a new token from your auth server and re-authenticate:

// Re-authenticate to pick up updated capabilities
await realtimeClient.auth.authorize();

• To immediately remove access, revoke issued tokens.
• If your capability JSON is too large for JWT or must remain confidential, use native Ably Tokens.