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:

Client setup

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

Spaces capabilities

Feature area	Required capabilities
Member locations and avatar stack	subscribe, presence
Live cursors	publish, subscribe
Component locking	subscribe, presence
History-aware collaboration	history

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:

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