Auth

The Auth interface is used to issue short-lived credentials to less-trusted clients without sharing your private API key. The recommended approach for most applications is to use Ably JWTs, which enable your server to mint tokens using standard JWT libraries.

Access it via the auth property of a Realtime client instance.

The Auth interface also supports the creation of Ably TokenRequest objects with createTokenRequest(), and the ability to obtain Ably Tokens from Ably with requestToken(). TokenRequest objects and Ably Tokens are only recommended over JWTs when your capability list is very large, or you need to keep your capabilities confidential.

const auth = realtime.auth;

Properties

The Auth interface has the following properties:

Authorize the client

Instructs the SDK to get a new token immediately. Once fetched, it will upgrade the current realtime connection to use the new token, or, if not connected, initiate a connection to Ably once the new token has been obtained. Also stores any tokenParams and authOptions passed in as the new defaults, to be used for all subsequent implicit or explicit token requests.

Any tokenParams and authOptions objects passed in will entirely replace (as opposed to being merged with) the current client.auth tokenParams and authOptions.

A subsidiary use case for authorize() is to preemptively trigger renewal of a token or to acquire a new token with a revised set of capabilities.

const tokenDetails = await realtime.auth.authorize({ clientId: 'user-123' });
console.log(tokenDetails.token);

Parameters

The authorize() method takes the following parameters:

Returns

Promise<TokenDetails>

Returns a promise. The promise is fulfilled with a TokenDetails object containing the new token once the realtime connection has been successfully upgraded to use it. On failure to obtain a token or upgrade the token, the connection moves to the SUSPENDED or FAILED state and the promise is rejected with an ErrorInfo object.

Create a TokenRequest

Creates and signs an Ably TokenRequest based on the specified (or, if none specified, the SDK's stored) tokenParams and authOptions. Note this can only be used when the API key value is available locally. Otherwise, the Ably TokenRequest must be obtained from the key owner. Use this to generate an Ably TokenRequest in order to implement an Ably Token request callback for use by other clients.

Both authOptions and tokenParams are optional. When omitted or null, the defaults specified in the ClientOptions when the SDK was instantiated, or set later via authorize(), are used. Values passed in are used instead of (rather than being merged with) the default values.

Issuing an Ably TokenRequest to clients in favor of a token avoids sharing your private API key, as explained in token authentication.

const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'user-123' });
// Send tokenRequest JSON to the requesting client

Parameters

The createTokenRequest() method takes the following parameters:

Returns

Promise<TokenRequest>

Returns a promise. The promise is fulfilled with a TokenRequest object, or rejected with an ErrorInfo object.

Request an Ably Token

Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified tokenParams and authOptions.

Both authOptions and tokenParams are optional. When omitted or null, the defaults specified in the ClientOptions when the SDK was instantiated, or set later via authorize(), are used. Values passed in are used instead of (rather than being merged with) the default values.

Issuing an Ably TokenRequest to clients in favor of a token avoids sharing your private API key, as explained in token authentication.

Note that since you normally use the ClientOptions callbacks to authenticate dynamically, you'll rarely need to call requestToken() explicitly, but it's available when you need finer control.

const tokenDetails = await realtime.auth.requestToken();

Parameters

The requestToken() method takes the following parameters:

Returns

Promise<TokenDetails>

Returns a promise. The promise is fulfilled with a TokenDetails object, or rejected with an ErrorInfo object.

Revoke tokens

Revokes the tokens specified by the provided array of TokenRevocationTargetSpecifiers. Only tokens issued by an API key that had token revocation enabled before the token was issued can be revoked.

const result = await realtime.auth.revokeTokens(
  [{ type: 'clientId', value: 'user-123' }],
  { allowReauthMargin: true }
);
console.log(`${result.successCount} succeeded, ${result.failureCount} failed`);

Parameters

The revokeTokens() method takes the following parameters:

Returns

Promise<BatchResult>

Returns a promise. The promise is fulfilled with a BatchResult whose results array contains a success or failure entry for each specifier. The promise is rejected with an ErrorInfo object if the request itself fails.