Skip to main content
Use these instructions to install, authenticate and instantiate the Spaces SDK.

​
Authenticate

Spaces requires an authenticated client with a clientId to identify users. The recommended approach is:
  1. Client-side apps (browsers, mobile apps): Use JWT authentication with authCallback to fetch JWTs from your server
  2. Server-side apps (Node.js, Python, etc.): Use your API key directly
Sign up to Ably to create an API key in the dashboard or use the Control API to create an API programmatically. Your server will use this key to issue tokens to clients. API keys and tokens have a set of capabilities assigned to them that specify which operations, such as subscribe or publish can be performed on which resources. To use the Spaces SDK, the API key requires the following capabilities:
  • Publish
  • Subscribe
  • Presence
  • History
For space-scoped capabilities and channel architecture details, see Spaces authentication.

​
Client identification

Every Spaces client must have a clientId - this is a hard requirement. The Spaces SDK uses the clientId to identify users in the avatar stack, track their locations, display their cursors, and manage component locking. Your auth server sets the clientId when creating tokens. This ensures users can’t impersonate each other - the identity is controlled server-side, not by the client. If you try to connect without a clientId, the connection will fail.

​
Install

The Spaces SDK is built on top of the Ably JavaScript SDK and uses it to establish a connection with Ably. Therefore the Ably JavaScript SDK is installed alongside the Spaces SDK. Both SDKs are available as NPM modules and via CDN.

​
Using NPM

Install the Ably JavaScript SDK and the Spaces SDK: Import the SDKs into your project:

​
Using a CDN

Reference the Ably JavaScript SDK and the Spaces SDK within the <head> of your HTML file:

​
Instantiate

Authentication is configured on the Ably JavaScript SDK client, which the Spaces client wraps. The Spaces SDK itself doesn’t handle authentication directly - it uses the authenticated connection from the underlying Ably client. Instantiate a realtime client using the Ably JavaScript SDK and pass the generated client into the Spaces constructor. Use token authentication for browsers and mobile apps. Your auth server endpoint validates the user and returns an Ably token with the appropriate clientId: Your auth server endpoint (/api/ably-token) should authenticate the user and return a token with the user’s clientId. See the token authentication documentation for server implementation examples.

​
Server-side authentication

For server-side applications or local development, you can use an API key directly: A ClientOptions object may be passed to the Ably JavaScript SDK to further customize the connection. When using token authentication, the clientId is set by your auth server. When using API key authentication server-side, you must provide a clientId so that the client is identified.

​
Using Ably JWT (alternative)

If you have existing JWT-based authentication infrastructure (Auth0, Firebase, Cognito, or custom), you can create Ably JWTs directly without using the Ably SDK on your server:

​
Server (no Ably SDK required)

​
Client

Why choose JWT for Spaces?
  • No Ably SDK required on your server
  • Integrates with existing Auth0/Firebase/Cognito flows
  • Supports channel-scoped claims for user metadata
  • Eliminates client round-trip to Ably
See Token authentication for detailed guidance on when to use JWT vs Ably Tokens.

​
Client connections

A Spaces client exposes the underlying connection to Ably that is established via the Ably JavaScript SDK. This means that Spaces clients benefit from the same functionality available in the Ably JavaScript SDK, such as automatic transport selection and connection state recovery in the event of brief disconnections. Connections transition through multiple states throughout their lifecycle. Whilst these transitions are handled by the Ably SDK, there are certain cases where you may need to observe and handle them within your application. Ably SDKs enable these transitions to be observed and triggered using methods available on the connection object. The Spaces SDK exposes the underlying connection with spaces.connection, which is a reference to client.connection in the Ably JavaScript SDK.

Build docs developers (and LLMs) love

Get started for freeTalk to us