Warning: You are viewing an old version (1.1) of this documentation. We recommend you view the latest version 1.2.
API Reference

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 authorizeAuthorize.

The Auth object is available as the auth fieldAuth propertyauth propertyauth attribute of an Ably Realtime client instance.

Auth Propertiesio.ably.lib.rest.Auth MembersIO.Ably.AblyAuth PropertiesAbly::Auth AttributesARTAuth Properties

The ARTAuth object exposes the following public propertiesattributesmembers:

clientIdclient_idClientId

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

Auth Methodsio.ably.lib.rest.Auth MethodsIO.Ably.AblyAuth MethodsAbly::Auth MethodsARTAuth Methods

authorizeAuthorize

authorize(TokenParams tokenParams, AuthOptions authOptions, callback(ErrorInfo err, TokenDetails tokenDetails))Deferrable authorize(TokenParams token_params, AuthOptions auth_options) → yields TokenDetailsTokenDetails authorize(TokenParams tokenParams, AuthOptions authOptions)“Task:#token-details AuthorizeAsync(”TokenParams:#token-params?, AuthOptions?)authorize(tokenParams: ARTTokenParams?, authOptions: ARTAuthOptions?, callback: (ARTTokenDetails?, NSError?) → Void)

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

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

Parameters

token_paramstokenParams
an optional object containing the token parametersan optional TokenParams object containing the Ably Token parametersan optional set of key value pairs containing the token parameters for the authorization request
Type: TokenParams
auth_optionsauthOptions
an optional object containing the authentication optionsan optional TokenParams object containing the authentication optionsan optional set of key value pairs containing the authentication options for the authorization request
Type: AuthOptions
callback
is a function of the form: function(err, tokenDetails)
&block
yields a TokenDetails object
callback
called with a ARTTokenDetails object or an error

Callback result

On success, the callback will be called with the new TokenDetails object only once the realtime connection has been successfully upgraded to use the new token.

On failure to obtain an token or upgrade the token, the connection will move to the SUSPENDED or FAILED state, and the callback will be called with err containing an NSError object with the error response as defined in the Ably REST API documentation.

The authorize callback can therefore be used to only trigger an event once the new token has taken effect. This can be useful if, for example, you want to do attach to a new channel following a new channel capability being applied to the connection.

Callback result

On success, the callback will be called with the new TokenDetails only once the realtime connection has been successfully upgraded to use the new token.

On failure to obtain a token or upgrade the token, the connection will move to the SUSPENDED or FAILED state, and the callback will be called with err containing an ErrorInfo object with the error response as defined in the Ably REST API documentation.

The authorize callback can be used to trigger an event once the new token has taken effect. This can be useful if, for example, you want to do attach to a new channel following a new channel capability being applied to the connection.

Returns

On success, a new TokenDetails is returned only once the realtime connection has been successfully upgraded to use the new Ably Token.

On failure to obtain a token or upgrade the token, the connection will move to the SUSPENDED or FAILED state and an AblyException will be raised with the error response as defined in the Ably REST API documentation.

The synchronous authorize method can therefore be used to run subsequent code only once the new token has taken effect. This can be useful if, for example, you want to do attach to a new channel following a new channel capability being applied to the connection.

Returns

Returns a Task<TokenDetails> which needs to be awaited.

On success, a new TokenDetails is returned only once the realtime connection has been successfully upgraded to use the new token.

On failure to obtain a token or upgrade the token, the connection will move to the SUSPENDED or FAILED state and an AblyException will be raised with the error response as defined in the Ably REST API documentation.

By waiting for the authorize method return value, it can be used to run subsequent code only once the new token has taken effect. This can be useful if, for example, you want to do attach to a new channel following a new channel capability being applied to the connection.

Returns

A Deferrable object is returned from this method.

On success, the registered success callbacks for the Deferrable and any block provided to this method yields a TokenDetails only once the realtime connection has been successfully upgraded to use the new token.

On failure to obtain a token or upgrade the token, the connection will move to the SUSPENDED or FAILED state, triggering the errback callbacks of the Deferrable with an ErrorInfo object with the error response as defined in the Ably REST API documentation.

The authorize callbacks can therefore be used to trigger an event once the new Ably Token has taken effect. This can be useful if, for example, you want to do attach to a new channel following a new channel capability being applied to the connection.

Example

client.auth.authorize({ clientId: 'bob' }, function(err, tokenDetails) {
  if(err) {
    console.log('An error occurred; err = ' + err.toString());
  } else {
    console.log('Success! Realtime connection upgraded with new token: ' +
      tokenDetails.token);
  }
});
client.auth.authorize({ clientId: 'bob' }, function(err, tokenDetails) {
  if(err) {
    console.log('An error occurred; err = ' + err.toString());
  } else {
    console.log('Success! Realtime connection upgraded with new token: ' +
      tokenDetails.token);
  }
});
try {
  TokenParams tokenParams = new TokenParams();
  tokenParams.clientId = "bob";
  TokenDetails tokenDetails = client.auth.authorize(tokenParams, null);
  System.out.println("Success; token = " + tokenDetails.token);
} catch(AblyException e) {
  System.out.println("An error occurred; err = " + e.getMessage());
}
try {
  TokenParams tokenParams = new TokenParams {ClientId = "bob"};
  TokenDetails tokenDetails = await client.Auth.AuthorizeAsync(tokenParams);
  Console.WriteLine("Success; Token = " + tokenDetails.Token);
} catch (AblyException e) {
  Console.WriteLine("An error occurred; Error = " + e.Message);
}
client.auth.authorize(client_id: 'bob') do |token_details|
  puts "Success; token = #{token_details.token}"
end
ARTTokenParams *tokenParams = [[ARTTokenParams alloc] initWithClientId:@"Bob"];
[client.auth authorize:tokenParams options:nil callback:^(ARTTokenDetails *tokenDetails, NSError *error) {
    if (error) {
        NSLog(@"An error occurred; err = %@", error);
    } else {
        NSLog(@"Success; token = %@", tokenDetails.token);
    }
}];
let tokenParams = ARTTokenParams(clientId: "Bob")
client.auth.authorize(tokenParams, options: nil) { tokenDetails, error in
    guard let tokenDetails = tokenDetails else {
        print("An error occurred; err = \(error!)")
        return
    }
    print("Success; token = \(tokenDetails.token)")
}
createTokenRequestcreate_token_requestCreateTokenRequestAsync

createTokenRequest(TokenParams tokenParams, AuthOptions authOptions, callback(ErrorInfo err, TokenRequest tokenRequest))Deferrable create_token_request(TokenParams token_params, AuthOptions auth_options) → yields TokenRequestTokenRequest createTokenRequest(TokenParams tokenParams, AuthOptions authOptions)Task<TokenRequest> CreateTokenRequestAsync(TokenParams tokenParams, AuthOptions authOptions)createTokenRequest(tokenParams: ARTTokenParams?, options: ARTAuthOptions?, callback: (ARTTokenRequest?, NSError?) → Void)

Creates and signs an Ably TokenRequest based on the specified (or if none specified, the client library stored) token_params and auth_optionstokenParams 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 Ably TokenRequests in order to implement an Ably Token request callback for use by other clients.

Both auth_options and token_paramsauthOptions and tokenParams are optional. When omitted or null, 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 authorizeAuthorize 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 a token, see Token Authentication explained.

Parameters

token_paramstokenParams
an optional object containing the token parametersan optional TokenParams object containing the token parametersan optional set of key value pairs containing the token parameters for the Ably Token request
Type: TokenParams
auth_optionsauthOptions
an optional object containing the authentication optionsan optional TokenParams object containing the authentication optionsan optional set of key value pairs containing the authentication optionsan optional ARTTokenParams containing the authentication options
Type: AuthOptions
callback
is a function of the form: function(err, tokenRequest)
&block
yields a TokenRequest object
callback
called with a ARTTokenRequest object or an error

Callback result

On success, tokenRequest contains a TokenRequest JSON object.

On failure to issue a TokenRequest, err contains an ErrorInfo object with an error response as defined in the Ably REST API documentation.

Returns

On success, a TokenRequest object is returned.

Failure to issue a TokenRequest will raise an AblyException.

Returns

Returns a Task<string> which needs to be awaited.

On success, a TokenRequest object is returned.

Failure to issue a TokenRequest will raise an AblyException.

Returns

A Deferrable object is returned from this method.

On success, the registered success callbacks for the Deferrable and any block provided to this method yields a TokenRequest object.

Failure to issue a TokenRequest will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

Example

client.auth.createTokenRequest({ clientId: 'bob' }, function(err, tokenRequest) {
  if(err) {
    console.log('An error occurred; err = ' + err.message);
  } else {
    console.log('Success; token request = ' + tokenRequest);
  }
});
client.auth.createTokenRequest({ clientId: 'bob' }, function(err, tokenRequest) {
  if(err) {
    console.log('An error occurred; err = ' + err.message);
  } else {
    console.log('Success; token request = ' + tokenRequest);
  }
});
try {
  TokenParams tokenParams = new TokenParams();
  tokenParams.clientId = "bob";
  TokenRequest tokenRequest = client.auth.createTokenRequest(tokenParams, null);
  System.out.println("Success; token request issued");
} catch(AblyException e) {
  System.out.println("An error occurred; err = " + e.getMessage());
}
try {
    TokenParams tokenParams = new TokenParams {ClientId = "bob"};
    TokenRequest tokenRequest = await client.Auth.CreateTokenRequestAsync(tokenParams);
    Console.WriteLine("Success; token request issued");
} catch (AblyException e) {
    Console.WriteLine("An error occurred; err = " + e.Message);
}
client.auth.create_token_request(client_id: 'bob') do |token_request|
  puts "Success; token request = #{token_request}"
end
ARTTokenParams *tokenParams = [[ARTTokenParams alloc] initWithClientId:@"Bob"];
[client.auth createTokenRequest:tokenParams options:nil callback:^(ARTTokenRequest *tokenRequest, NSError *error) {
    if (error) {
        NSLog(@"An error occurred; err = %@", error);
    } else {
        NSLog(@"Success; token request = %@", tokenRequest);
    }
}];
let tokenParams = ARTTokenParams(clientId: "Bob")
client.auth.createTokenRequest(tokenParams, options: nil) { tokenRequest, error in
    guard let tokenRequest = tokenRequest else {
        print("An error occurred; err = \(error!)")
        return
    }
    print("Success; token request = \(tokenRequest)")
}
requestTokenrequest_tokenRequestTokenAsync

requestToken(TokenParams tokenParams, AuthOptions authOptions, callback(ErrorInfo err, TokenDetails tokenDetails))Deferrable request_token(TokenParams token_params, AuthOptions auth_options) → yields TokenDetailsTokenDetails requestToken(TokenParams tokenParams, AuthOptions authOptions)async Task<TokenDetails> RequestTokenAsync(TokenParams? tokenParams, AuthOptions? options)requestToken(tokenParams: ARTTokenParams?, withOptions: ARTAuthOptions?, callback: (ARTTokenDetails?, NSError?) → Void)

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

Both auth_options and token_paramsauthOptions and tokenParams are optional. When omitted or null, 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 authorizeAuthorize 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 a token, see Token Authentication explained.

Parameters

token_paramstokenParams
an optional object containing the token parametersan optional TokenParams object containing the token parametersan optional set of key value pairs containing the token parameters for the requested token
Type: TokenParams
auth_optionsauthOptions
an optional object containing the authentication optionsan optional TokenParams object containing the authentication optionsan optional set of key value pairs containing the authentication options for the requested Ably Token
Type: AuthOptions
callback
is a function of the form: function(err, tokenDetails)
&block
yields a TokenDetails object
callback
called with a ARTTokenDetails object or an error

Callback result

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

On failure to obtain an Ably Token, err contains an ErrorInfoNSError object with an error response as defined in the Ably REST API documentation.

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.

Returns

Returns a Task<TokenDetails> which needs to be awaited.

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.

Returns

A Deferrable object is returned from this method.

On success, the registered success callbacks for the Deferrable and any block provided to this method yields a TokenDetails object containing the details of the new Ably Token along with the token string.

Failure to obtain an Ably Token will trigger the errback callbacks of the Deferrable with an ErrorInfo object containing an error response as defined in the Ably REST API documentation.

Example

client.auth.requestToken({ clientId: 'bob'}, function(err, tokenDetails){
  if(err) {
    console.log('An error occurred; err = ' + err.message);
  } else {
    console.log('Success; token = ' + tokenDetails.token);
  }
});
client.auth.requestToken({ clientId: 'bob'}, function(err, tokenDetails){
  if(err) {
    console.log('An error occurred; err = ' + err.message);
  } else {
    console.log('Success; token = ' + tokenDetails.token);
  }
});
client.auth.request_token(client_id: 'bob') do |token_details|
  puts "Success; token = #{token_details.token}"
end
try {
  TokenParams tokenParams = new TokenParams();
  tokenParams.clientId = "bob";
  TokenDetails tokenDetails = client.auth.requestToken(tokenParams, null);
  System.out.println("Success; token = " + tokenDetails.token);
} catch(AblyException e) {
  System.out.println("An error occurred; err = " + e.getMessage());
}
try {
  TokenParams tokenParams = new TokenParams {ClientId = "bob"};
  TokenDetails tokenDetails = await client.Auth.RequestTokenAsync(tokenParams);
  Console.WriteLine("Success; token = " + tokenDetails.Token);
} catch (AblyException e) {
  Console.WriteLine("An error occurred; err = " + e.Message);
}
ARTTokenParams *tokenParams = [[ARTTokenParams alloc] initWithClientId:@"Bob"];
[client.auth requestToken:tokenParams withOptions:nil callback:^(ARTTokenDetails *tokenDetails, NSError *error) {
  if (error) {
    NSLog(@"An error occurred; err = %@", error);
  } else {
    NSLog(@"Success; token = %@", tokenDetails.token);
  }
}];
let tokenParams = ARTTokenParams(clientId: "Bob")
client.auth.requestToken(tokenParams, withOptions: : nil) { tokenDetails, error in
  guard let tokenDetails = tokenDetails else {
    print("An error occurred; err = \(error!)")
    return
}
  print("Success; token = \(tokenDetails.token)")
}

AuthOptions ObjectARTAuthOptionsAuthOptions Hashio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions

AuthOptions is a plain JavaScript object and is used when making authentication requests. If passed in, an authOptions object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported:

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:

AuthOptions is a Dict 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 Dict:

AuthOptions is an Associative Array and is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated. The following named keys and values can be added to the Associative Array:

ARTAuthOptions is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated.

PropertiesMembersAttributesAttributes

authCallbackAuthCallbackauth_callback:auth_callback
A functionfunction with the form function(tokenParams, callback(err, tokenOrTokenRequest))TokenCallback instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. See an authentication callback example or our authentication documentation for details of the Ably TokenRequest format and associated API calls.
Type: CallableTokenCallbackProcFunc<TokenParams, Task<TokenDetails>>
authUrlAuthUrl:auth_urlauth_url
A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest ; a TokenDetails (in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.
Type: StringUriNSURL
authMethodAuthMethodauth_method:auth_method
GET:get The HTTP verb to use for the request, either GET:get or POST:post
Type: StringSymbolHttpMethod
authHeadersAuthHeadersauth_headers:auth_headers
A set of key value pair headers to be added to any request made to the authUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response. If the authHeaders object contains an authorization key, then withCredentials will be set on the xhr request.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>
authParamsAuthParams:auth_paramsauth_params
A set of key value pair params to be added to any request made to the authUrlAuthUrl. When the authMethodAuthMethod is GET, query params are added to the URL, whereas when authMethodAuthMethod is POST, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
Type: ObjectHashAssociative ArrayParam[]Dictionary<string, string>NSArray<NSURLQueryItem *>[NSURLQueryItem]/Array<NSURLQueryItem>
tokenDetailsTokenDetailstoken_details:token_details
An authenticated TokenDetails object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: TokenDetails
keyKey:keykey
Optionally the API key to use can be specified as a full key string; if not, the API key passed into ClientOptions when instancing the Realtime or REST library is used
Type: String
queryTimeQueryTime:query_timequery_time
false If true, the library will query the Ably servers for the current time when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
Type: Boolean
tokenToken:token
An authenticated token. This can either be a TokenDetails object, a TokenRequest object, or token string (obtained from the tokenToken property of a TokenDetails component of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about Token authentication
Type: String, TokenDetails or TokenRequest

TokenDetails ObjectARTTokenDetailsio.ably.lib.types.TokenDetailsAbly::Models::TokenDetailsIO.Ably.TokenDetails

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

PropertiesMembersAttributes

tokenToken
The Ably Token itself. A typical Ably Token string may appear like xVLyHw.A-pwh7w4QuY-MULgxchrFeFoiHuFt3FwMzQy0f_FXfPQSCm7cU
Type: String
expiresExpires
The time (in milliseconds since the epoch)The time at which this token expires
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate
issuedIssued
The time (in milliseconds since the epoch)The time at which this token was issued
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate
capabilityCapability
The capability associated with this Ably Token. The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. Read more about authentication and capabilities
Type: StringCapability
clientIdclient_idClientId
The client ID, if any, bound to this Ably Token. If a client ID is included, then the Ably Token authenticates its bearer as that client ID, and the Ably Token may only be used to perform operations on behalf of that client ID. The client is then considered to be an identified client
Type: String

Methods

expired?
True when the token has expired
Type: Boolean

Methods

is_expired()
True when the token has expired
Type: Boolean

Methods

IsValidToken()
True if the token has not expired
Type: Boolean

TokenDetails constructors

TokenDetails.fromJsonTokenDetails.from_json

TokenDetails.fromJson(String json) → TokenDetailsTokenDetails.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

json
a TokenDetails-like deserialized object or JSON stringified TokenDetails.
Type: Object, String

Returns

A TokenDetails object

TokenParams ObjectARTTokenParamsTokenParams Hashio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams

TokenParams is a plain JavaScript object and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following attributes can be defined on the object:

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:

TokenParams is a Dict and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following keys-value pairs can be added to the Dict:

TokenParams is an Associative Array and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following named keys and values can be added to the Associative Array:

TokenParams is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token.

ARTTokenParams is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token.

PropertiesMembersAttributesAttributes

capabilityCapability:capability
JSON stringified capability of the Ably Token. If the Ably Token request is successful, the capability of the returned Ably Token will be the intersection of this capability with the capability of the issuing key. Find our more about how to use capabilities to manage access privileges for clients. Type: StringCapability
clientIdClientIdclient_id:client_id
A client ID, used for identifying this client when publishing messages or for presence purposes. The clientIdclient_idClientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a clientIdclient_idClientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientIdclient_idClientId specified here conflicts with the clientIdclient_idClientId implicit in the token. Find out more about client identities
Type: String
nonceNonce:nonce
An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected.
Type: String
timestampTimestamp:timestamp
The timestamp (in milliseconds since the epoch)The timestamp of this request. timestamp, in conjunction with the nonce, is used to prevent requests for Ably Token from being replayed.
Type: IntegerLong IntegerTimeNSDateDateTimeOffset
ttlTtl:ttl
1 hour Requested time to live for the Ably Token being created in millisecondsin secondsas a NSTimeIntervalas a TimeSpan. When omitted, the Ably REST API default of 60 minutes is applied by Ably
Type: Integer (milliseconds)Integer (seconds)NSTimeIntervalLong IntegerTimeSpan

TokenRequest ObjectARTTokenRequestAbly::Models::TokenRequestio.ably.lib.rest.Auth.TokenRequestIO.Ably.TokenRequest

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

PropertiesMembersAttributes

keyNamekey_nameKeyName
The key name of the key against which this request is made. The key name is public, whereas the key secret is private
Type: String
ttlTtl
Requested time to live for the Ably Token in millisecondsin secondsas a TimeSpan. If the Ably TokenRequest is successful, the TTL of the returned Ably Token will be less than or equal to this value depending on application settings and the attributes of the issuing key.
Type: IntegerTimeSpanNSTimeInterval
timestampTimestamp
The timestamp of this request in milliseconds
Type: IntegerLong IntegerTimeDateTimeOffsetNSDate
capabilityCapability
Capability of the requested Ably Token. If the Ably TokenRequest is successful, the capability of the returned Ably Token will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. Read more about authentication and capabilities
Type: String
clientIdclient_idClientId
The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to perform operations on behalf of that client ID
Type: String
nonceNonce
An opaque nonce string of at least 16 characters
Type: String
macMac
The Message Authentication Code for this request
Type: String

TokenRequest constructors

TokenRequest.fromJsonTokenRequest.from_json

TokenRequest.fromJson(String json) → TokenRequestTokenRequest.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

json
a TokenRequest-like deserialized object or JSON stringified TokenRequest.
Type: Object, String

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 xVLyHw.5Jktvw:Ipj3xz2XksJbVYXpR6z1kwhbMVbDjrSCgR7YFGrfpsY will have key name xVLyHw.5Jktvw
  • 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-capabilityJSON 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.

The following is an example of creating an Ably JWT:

var header = {
  "typ":"JWT",
  "alg":"HS256",
  "kid": "xVLyHw.5Jktvw"
};
var currentTime = Math.round(Date.now()/1000);
var claims = {
  "iat": currentTime, /* current time in seconds */
  "exp": currentTime + 3600, /* time of expiration in seconds */
  "x-ably-capability": "{\"*\":[\"*\"]}"
};
var base64Header = btoa(header);
var base64Claims = btoa(claims);
/* Apply the hash specified in the header */
var signature = hash((base64Header + "." + base64Claims), "Ipj3xz2XksJbVYXpR6z1kwhbMVbDjrSCgR7YFGrfpsY");
var ablyJwt = base64Header + "." + base64Claims + "." + signature;

Note: At present Ably does not support asymmetric signatures based on a keypair belonging to a third party. If this is something you’d be interested in, please get in touch.


Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.