Authentication overview

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

Recommended authentication

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.