Authentication

Ably clients can authenticate with Ably in one of two ways. They can use Basic Authentication or Token Authentication. Basic Authentication makes use of the customer’s API key) to connect with Ably. Token Authentication requires a server to provide an Ably Token, an Ably TokenRequest, an Ably JWT (JSON Web Token), or an External JWT with an embedded Ably-compatible token to the client. Token Authentication, in most cases, is the recommended strategy due to it providing robust access control and stringent security measures.

This page of documentation is intended to describe the REST Authentication API and is not intended to explain in depth how Ably’s authentication works. If you are new to Ably and/or the authentication schemes, we strongly recommend that you get acquainted with the following first:

• Getting started with Ably’s authentication
• Selecting the right authentication scheme
• Basic Authentication explained
• Token Authentication explained

If you’re the kind of person who prefers to dive into code, we have client-server authentication tutorials.

Basic Authentication uses one of the API keys configured via the application dashboard as the authentication token. Basic Authentication is the simplest method to use but has some important limitations described in detail in the Basic Authentication documentation.

Here is a straightforward example of using Basic Authentication when instancing an Ably REST client library.

JavaScriptNode.jsRubyPythonPHPJavaC# .NETSwiftObjective-CGo
JavaScript

var rest = new Ably.Rest({ key: '<loading API key, please wait>' });

API Key:
Demo Only
Copy
Copied!

Token Authentication uses an Ably-compatible token to authenticate with Ably. This can be an Ably Token obtained via the REST API requestToken endpoint, an Ably JWT signed by your API key, or an External JWT object with an embedded Ably-compatible token.

Tokens are authentication credentials that are short-lived, and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope – such as a limited set of access rights or capabilities or being limited to use by a specific clientId identity – and therefore token-based authentication provides the flexibility to implement access and identity control policies in the application. See the Token Authentication documentation for more details. To initialize the REST library to a previously obtained Ably Token or Ably JWT, set the token or tokenDetails attribute of ClientOptions to the token.

Below is an example that creates an instance of a REST library using Token Authentication with a means to reissue tokens as required.

Typically, in a browser environment, the authUrl provided would be a URL relative to an endpoint under the same origin. This endpoint issues tokens to trusted clients. Client requests can, for example, be trusted based on session cookies.

JavaScriptNode.jsRubyPythonPHPJavaC# .NETObjective-CSwiftGo
JavaScript

const rest = new Ably.Rest({ authUrl: '/auth' });

Copy
Copied!

Auth options uses properties set with AuthOptions to override the default authentication values set when instantiating the client library. You can also embed AuthOptions into your ClientOptions while instantiating the client library.

There are several auth options you can specify along with authUrl and authCallback:

• authMethod – when authUrl is called, the default “GET“ method will be used, unless “POST“ is specified.
• authHeaders – allows you to pass additional headers as required, depending on your use case.
• authParams – allows you to pass additional query parameters, depending on your use case.

JavaScriptNode.js
JavaScript

const rest = new Ably.Rest({ authUrl: "/auth", authMethod: "POST", authParams: { p1: param1, b: param2}, authHeaders: {h1: header1, h2: header2} });

Copy
Copied!

For non-browser clients, an authentication callback is the preferred method of implementing token refresh, although browser clients can also use authCallback if the use case requires it. This relies on your application communicating securely with your own servers to obtain a token.

The following code sample shows an example of using an authCallback in a client:

JavaScriptNode.js
JavaScript

const rest = new Ably.Rest({
  authCallback: (tokenParams, callback) => {
    // implement your callback here
  },
});

Copy
Copied!

When deciding on which authentication method you will be using, it is recommended to 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 table below should be used as a rough guide as to what you should 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:

When a client is authenticated and connected to Ably, they are considered to be an authenticated client. However, whilst an authenticated client has a verifiable means to authenticate with Ably, they do not necessarily have an identity. When a client is assigned a trusted identity (i.e. a clientId), then they are considered to be an identified client and for all operations they perform with the Ably service, their clientId field will be automatically populated and can be trusted by other clients.

We encourage customers to always issue tokens to clients so that they authenticate using the short-lived token and do not have access to a customer’s private API keys. Since the customer can then control the clientId that may be used by any of its clients, all other clients can rely on the validity of the clientId in published messages and of members present in presence channels.

The following example demonstrates how to issue an Ably TokenRequest with an explicit clientId that, when used by a client, will then be considered an identified client.

JavaScriptNode.jsRubyPythonPHPJavaC# .NETObjective-CSwiftGo
JavaScript

var rest = new Ably.Rest({ key: '<loading API key, please wait>' });
rest.auth.createTokenRequest({ clientId: 'Bob' }, function(err, tokenRequest) {
  /* ... issue the TokenRequest to a client ... */
})

API Key:
Demo Only
Copy
Copied!

View the Authentication API Reference.