Authentication overview

Before a client or server can issue requests to Ably, such as subscribe to channels, or publish messages, it must authenticate with Ably. Authentication requires an Ably API key.

Every Ably app can have one or more API keys associated with it in order to authenticate directly with Ably, or to issue tokens with. API keys can be created with different capabilities and any tokens issued using that API key can only permit a subset of those capabilities.

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

The API key is made up of three parts:

1. I2E_JQ is the public app ID (the part before the first period)
2. OqUdfg is the public app key ID (the part after the period and before the colon). I2E_JQ.OqUdfg is the public API key ID (both the public app ID and app key ID together)
3. EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0 is the API key secret and should never be shared with untrusted parties (the part after the colon)

The API key secret is private and should never be made public. This API key string is used in all Ably SDKs and for authentication with the REST API.

API keys are created in the Ably dashboard. You can also create an API key programmatically using the Control API.

To create an API key in the Ably dashboard:

1. In your Ably dashboard click the API Keys tab.
2. Click the Create a new API key button.
3. Enter a name for your API key – this will help you identify the specific key when you have many keys created.
4. Select the capabilities you want to apply to the key. Clients connecting with this key will be restricted to these capabilities.
5. Optionally you can select whether to make tokens generated from this key to be revocable or not.
6. Optionally select whether you want to restrict the scope of the key to channels, queues, or specific channels and queues using resource names and wildcards.

The two authentication mechanisms available to authenticate with Ably are:

1. Basic authentication, which uses your Ably API key directly.
2. Token authentication, which uses short-lived tokens for access. These tokens are periodically renewed, and can be revoked if required.

Token authentication is the recommended authentication mechanism on the client-side, as it provides more fine-grained access control and limits the risk of exposing your Ably API key.

In production systems you should never use basic authentication on the client-side as it exposes your Ably API key. API keys don’t have an expiry, so once compromised, they could be used indefinitely by an attacker.

Tokens have an expiry, and so there is only a small period of time during which the compromised token can be used. It is also possible to revoke tokens, should that be necessary for security reasons.

Use basic authentication on the server-side. You should never use token authentication server-side, as this results in unnecessary overhead due the server needing to periodically make token requests to authenticate itself.

When deciding on which authentication method you will be using, it is recommended you bear in mind the principle of least privilege.

A client should ideally only possess the credentials and rights that it needs to accomplish what it wants. This way, if the credentials are compromised, the rights that can be abused by an attacker are minimized.

The following table provides guidelines on what to consider when choosing your authentication method. Many applications will most naturally use a mixed strategy: one or more trusted application servers will use basic authentication to access the service and issue tokens over HTTPS, whereas remote browsers and devices will use individually issued tokens: