Authentication

This is the Authentication API Reference.

Tokens

In the documentation, references to Ably-compatible tokens typically refer either to an Ably Token, or an Ably JWT. For Ably Tokens, this can either be referring to the TokenDetails object that contain the token string or the token string itself. TokenDetails objects are obtained when requesting an Ably Token from the Ably service and contain not only the token string in the token attribute, but also contain attributes describing the properties of the Ably Token. For Ably JWT, this will be simply referring to a JWT which has been signed by an Ably private API key.

Auth object

The principal use-case for the Auth object is to create Ably TokenRequest objects with createTokenRequest or obtain Ably Tokens from Ably with requestToken, and then issue them to other "less trusted" clients. Typically, your servers should be the only devices to have a private API key, and this private API key is used to securely sign Ably TokenRequest objects or request Ably Tokens from Ably. Clients are then issued with these short-lived Ably Tokens or Ably TokenRequest objects, and the libraries can then use these to authenticate with Ably. If you adopt this model, your private API key is never shared with clients directly.

A subsidiary use-case for the Auth object is to preemptively trigger renewal of a token or to acquire a new token with a revised set of capabilities by explicitly calling authorize.

The Auth object is available as the auth attribute of an Ably REST client instance.

Ably::Auth Attributes

The Auth object exposes the following public attributes:

client_id

The client ID string, if any, configured for this client connection. See identified clients for more information on trusted client identifiers.

Ably::Auth Methods

authorize

TokenDetails authorize(TokenParams token_params, AuthOptions auth_options)

Instructs the library to get a new token immediately using the specified token_params and auth_options (or if none specified, the client library defaults). Also stores any token_params and auth_options passed in as the new defaults, to be used for all subsequent implicit or explicit token requests.

Any token_params and auth_options objects passed in will entirely replace (as opposed to being merged with) the currently saved token_params and auth_options.

Parameters

Returns

On success, a TokenDetails object containing the details of the new or existing token along with the token string is returned.

Failure to obtain an token will raise an AblyException.

Example

token_details = client.auth.authorize(client_id: 'bob')
puts "Success; token = #{token_details.token}"

create_token_request

TokenRequest create_token_request(TokenParams token_params, AuthOptions auth_options)

Creates and signs an Ably TokenRequest based on the specified token_params and auth_options. Note this can only be used when the API key value is available locally, due to it being required to sign the Ably TokenRequest. Otherwise, Ably TokenRequests must be obtained from the key owner. Use this to generate Ably TokenRequests in order to implement an Ably Token request callback for use by other clients.

Both auth_options and token_params are optional. When omitted or nil, the default Ably-compatible token parameters and authentication options for the client library are used, as specified in the ClientOptions when the client library was instantiated, or later updated with an explicit authorize request. Values passed in will be used instead of (rather than being merged with) the default values.

To understand why an Ably TokenRequest may be issued to clients in favor of an Ably Token, see Token Authentication explained.

Parameters

Returns

On success, a TokenRequest object is returned.

Failure to issue a TokenRequest will raise an AblyException.

Example

token_request = client.auth.create_token_request(client_id: 'bob')
puts "Success; token request = #{token_request}"

request_token

TokenDetails request_token(TokenParams token_params, AuthOptions auth_options)

Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified token_params and auth_options.

Both auth_options and token_params are optional. When omitted or nil, the default token parameters and authentication options for the client library are used, as specified in the ClientOptions when the client library was instantiated, or later updated with an explicit authorize request. Values passed in will be used instead of (rather than being merged with) the default values.

To understand why an Ably TokenRequest may be issued to clients in favor of an Ably Token, see Token Authentication explained.

Parameters

Returns

On success, a TokenDetails object containing the details of the new Ably Token along with the token string is returned.

Failure to obtain an Ably Token will raise an AblyException.

Example

token_details = client.auth.request_token(client_id: 'bob')
puts "Success; token = #{token_details.token}"

Related types

AuthOptions Hash

AuthOptions is a Hash object and is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Hash:

Attributes

Ably::Models::TokenDetails

TokenDetails is a type providing details of Ably Token string and its associated metadata.

Attributes

Methods

TokenDetails constructors

TokenDetails.from_json

TokenDetails.from_json(String json) -> TokenDetails

A static factory method to create a TokenDetails from a deserialized TokenDetails-like object or a JSON stringified TokenDetails. This method is provided to minimize bugs as a result of differing types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenDetails object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to the Ably standard which is milliseconds. By using the fromJson method when constructing a TokenDetails, Ably ensures that all fields are consistently serialized and deserialized across platforms.

Parameters

Returns

A TokenDetails object

TokenParams Hash

TokenParams is a Hash object and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following key symbol values can be added to the Hash:

Attributes

Ably::Models::TokenRequest

TokenRequest is a type containing parameters for an Ably TokenRequest. Ably Tokens are requested using Auth#request_token

Attributes

TokenRequest constructors

TokenRequest.from_json

TokenRequest.from_json(String json) -> TokenRequest

A static factory method to create a TokenRequest from a deserialized TokenRequest-like object or a JSON stringified TokenRequest. This method is provided to minimize bugs as a result of differing types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenRequest object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to the Ably standard which is milliseconds. By using the fromJson method when constructing a TokenRequest, Ably ensures that all fields are consistently serialized and deserialized across platforms.

Parameters

Returns

A TokenRequest object

Ably JWT

An Ably JWT is not strictly an Ably construct, rather it is a JWT which has been constructed to be compatible with Ably. The JWT must adhere to the following to ensure compatibility:

• The JOSE header must include:
  • kid - Key name, such that an API key of {{API_KEY}} will have key name {{API_KEY_NAME}}
• The JWT claim set must include:
  • iat - time of issue in seconds
  • exp - expiry time in seconds
• The JWT claim set may include:
  • x-ably-capability - JSON text encoding of the capability
  • x-ably-clientId - client ID

Arbitrary additional claims and headers are supported (apart from those prefixed with x-ably- which are reserved for future use).

The Ably JWT must be signed with the secret part of your Ably API key using the signature algorithm HS256 (HMAC using the SHA-256 hash algorithm). View the JSON Web Algorithms (JWA) specification for further information.

We recommend you use one of the many JWT libraries available for simplicity when creating your JWTs.