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
- Your auth server authenticates the user.
- Your auth server issues an Ably-compatible token (JWT format is recommended for most apps).
- The client SDK fetches tokens with
authCallbackand refreshes them automatically before expiry. - 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 intoSpaces 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 channelsmy-namespace:*- all spaces in themy-namespace:namespace*- all spaces
Token lifecycle and permission updates
- With
authCallbackorauthUrl, 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.