SDK setup

Open in

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:

Client-side apps (browsers, mobile apps): Use JWT authentication with authCallback to fetch JWTs from your server
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:

npm install @ably/spaces

Import the SDKs into your project:

JavaScript

import Spaces from '@ably/spaces';
import { Realtime } from 'ably';

Using a CDN

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

JavaScript

<script src="https://cdn.ably.com/lib/ably.min-2.js"></script>
<script src="https://cdn.ably.com/spaces/0.4/iife/index.bundle.js"></script>

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.

Client-side authentication (recommended)

Use token authentication for browsers and mobile apps. Your auth server endpoint validates the user and returns an Ably token with the appropriate clientId:

JavaScript

// Client-side: Token authentication (recommended for browsers)

// If installing via NPM
const client = new Realtime({
  authCallback: async (tokenParams, callback) => {
    try {
      const response = await fetch('/api/ably-token');
      const token = await response.text();
      callback(null, token);
    } catch (error) {
      callback(error, null);
    }
  },
});
const spaces = new Spaces(client);

// If installing via CDN
const client = new Ably.Realtime({
  authCallback: async (tokenParams, callback) => {
    try {
      const response = await fetch('/api/ably-token');
      const token = await response.text();
      callback(null, token);
    } catch (error) {
      callback(error, null);
    }
  },
});
const spaces = new Spaces(client);

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:

JavaScript

// Server-side only: API key authentication
// WARNING: Never use this in client-side code (browsers, mobile apps)
const client = new Realtime({
  key: process.env.ABLY_API_KEY,
  clientId: 'server-process-1'
});
const spaces = new Spaces(client);

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)

JavaScript

import jwt from 'jsonwebtoken';

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

app.get('/api/ably-jwt', async (req, res) => {
  // Your existing auth middleware validates the user
  const userId = req.user.id;

  const ablyJwt = jwt.sign(
    {
      'x-ably-capability': JSON.stringify({
        '*': ['publish', 'subscribe', 'presence', 'history'],
      }),
      'x-ably-clientId': userId,
    },
    keySecret,
    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
  );

  res.send(ablyJwt);
});

Client

JavaScript

const client = new Realtime({
  authCallback: async (tokenParams, callback) => {
    try {
      const response = await fetch('/api/ably-jwt', {
        headers: { 'Authorization': `Bearer ${yourAppJwt}` },
      });
      const jwt = await response.text();
      callback(null, jwt);
    } catch (error) {
      callback(error, null);
    }
  },
});
const spaces = new Spaces(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.