Authentication Overview

All interactions between a client and the Ably service must be authenticated.

Recommended authentication

Environment	Recommended Method	Details
Client-side (browsers, mobile apps)	Token authentication	Your server issues tokens (JWT recommended); clients use authCallback to fetch them
Server-side (Node.js, Python, etc.)	Basic authentication	Use your API key directly in trusted environments

Ably API keys

Every Ably app can have one or more API keys associated with it. API keys authenticate directly with Ably or are used to issue tokens.

Keys can have different capabilities, and tokens issued from a key can only request a subset of those capabilities.

API key format

An Ably API key string has the following format: I2E_JQ.OqUdfg:EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0

The API key has three parts:

1. I2E_JQ - the public app ID
2. OqUdfg - the public key ID (I2E_JQ.OqUdfg together form the public API key ID)
3. EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0 - the API key secret (never share this)

Create an API key

API keys are created in the Ably dashboard or programmatically via the Control API.

To create an API key in the dashboard:

1. Click the API Keys tab in your dashboard.
2. Click Create a new API key.
3. Enter a name to identify the key.
4. Select the capabilities to apply.
5. Optionally enable token revocation.
6. Optionally restrict scope to specific channels or queues.

Selecting an authentication mechanism

Ably supports two authentication mechanisms:

1. Token authentication: Short-lived Ably Tokens that expire and can be revoked. Recommended for clients. Use JWTs for most applications, or native Ably Tokens when JWTs aren’t suitable.
2. Basic authentication: Uses your API key directly. Use only on trusted servers.

When deciding which method to use, apply the principle of least privilege: a client should only possess the credentials and rights it needs. If credentials are compromised, the damage is minimized.

Many applications use a mixed strategy: trusted servers use basic authentication to issue tokens, while browsers and devices use those tokens.

Scenario	Recommended	Details
Client-side (browsers, mobile)	JWT	Use JWT authentication. No Ably SDK needed on your server
Server-side (trusted environment)	Basic auth	Use your API key directly
Fine-grained per-user access control	JWT or Ably Token	Set capabilities per token
Time-limited or revocable access	JWT or Ably Token	Tokens expire and can be revoked
Users must be identified	JWT or Ably Token	Set clientId server-side

Next steps

• Learn about basic authentication
• Learn about token authentication
• Understand capabilities for access control