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:

Scenario Basic Token Description
Your scripts may be exposed No Yes If the script, program or system holding the key is exposed, for example on a user’s device, you should not embed an API key and instead use token authentication. If the script is on a secure environment such as your own server, an API key with basic authentication is fine.
Your connection may be insecure No Yes If there is a risk of exposure of the client’s credentials, either directly or over an insecure, or insecurely proxied, connection, token authentication should be used. If you are sure the connection is secure and unmediated, basic authentication is acceptable.
You have no server to control access Yes No If you do not have your own server to perform authentication and provide tokens to users, you’ll need to use basic authentication.
You require fine-grained access control No Yes If you need to provide privileges on a user-by-user basis, you’d be better using token authentication. If you only need a few access control groups, basic authentication is reasonable.
Users need restricted periods of access No Yes If you need users to only have access for a certain period of time, or the ability to revoke access, token authentication is needed. If users are able to always have access, basic authentication is acceptable.
Users need to identify themselves Partial Yes If the user can be trusted to identify itself, basic authentication is fine. If the user cannot be trusted however, token authentication is better as it allows for a trusted token distributor to identify the user instead.
Ably API keys