Spaces authentication

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

How Spaces maps to channels

A logical space is implemented using underlying Pub/Sub channels. Capability expressions should account for both channel types:

• Main space channel: your-space (presence and member locations)
• Cursors channel: your-space-cursors (high-frequency cursor updates)

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 Spaces.

Server setup

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

// Server-side JWT with space-scoped capabilities import jwt from 'jsonwebtoken'; const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':'); const ablyJwt = jwt.sign( { 'x-ably-capability': JSON.stringify({ 'your-space': ['publish', 'subscribe', 'presence', 'history'], 'your-space-cursors': ['publish', 'subscribe'], }), 'x-ably-clientId': userId, }, keySecret, { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' } );

Client setup

import Spaces from '@ably/spaces'; import { Realtime } from 'ably'; const realtimeClient = new 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 spaces = new Spaces(realtimeClient);

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

Spaces capabilities

Space-scoped capabilities

You can scope capabilities to specific spaces or all spaces:

• my-space - a specific space and its associated channels
• my-namespace:* - all spaces in the my-namespace: namespace
• * - all spaces

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.