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, 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.
Understanding the Ably authentication schemes
This page of documentation is intended to describe the Realtime 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
Tutorials
If you’re the kind of person who prefers to dive into code, we have client-server authentication tutorials.
Basic Authentication
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 to connect to Ably:
var realtime = new Ably.Realtime({ key: 'xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-' });
var realtime = new Ably.Realtime({ key: 'xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-' });
realtime = Ably::Realtime.new(key: 'xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-')
ClientOptions options = new ClientOptions();
options.key = "xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-";
AblyRealtime realtime = new AblyRealtime(options);
let realtime = ARTRealtime(key: "xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-")
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-"];
AblyRealtime realtime = AblyRealtime("xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-");
Token Authentication
Look at the general authentication documentation for more in-depth information on Token Authentication.
Token Authentication uses an Ably-compatible token to authenticate with Ably. This can be an Ably Token obtained via the REST API requestToken
RequestToken
request_token
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
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 Realtime library to a previously obtained Ably Token
or Ably JWT
, set the :token
or :token_details
token
or token_details
Token
or TokenDetails
token
or tokenDetails
attribute of ClientOptions
to said token.
Below is a rather contrived yet straightforward example that instances a Realtime library using Token Authentication with a means to reissue tokens as required. Typically, in a browser environment, the authUrl
AuthUrl
provided would be a relative URL to a local endpoint that is used to issue tokens to trusted clients. Client requests can, for example, be trusted based on session cookies. For non-browser clients, an authentication callback is preferred thus relying on your application to communicate securely with your own servers to obtain a token.
var realtime = new Ably.Realtime({ authUrl: 'http://my.website/auth' });
var realtime = new Ably.Realtime({ authUrl: 'http://my.website/auth' });
realtime = Ably::Realtime.new(auth_url: 'http://my.website/auth')
ClientOptions options = new ClientOptions();
options.authUrl = "http://my.website/auth";
AblyRealtime realtime = new AblyRealtime(options);
ARTClientOptions *options = [[ARTClientOptions alloc] init];
options.authUrl = [NSURL URLWithString:@"http://my.website/auth"];
ARTRealtime *realtime = [[ARTRealtime alloc] initWithOptions:options];
let options = ARTClientOptions()
options.authUrl = NSURL(string: "http://my.website/auth")
let realtime = ARTRealtime(options: options)
ClientOptions options = new ClientOptions();
options.AuthUrl = new Uri("http://my.website/auth");
AblyRealtime realtime = new AblyRealtime(options);
Selecting an authentication mechanism
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.:
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. |
Identified clients
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 client_id
ClientId
clientId
), then they are considered to be an identified client and for all operations they perform with the Ably service, their client_id
ClientId
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 client_id
ClientId
clientId
that may be used by any of its clients, all other clients can rely on the validity of the client_id
ClientId
clientId
in published messages and of members present in presence channels.
The following example demonstrates how to issue an Ably TokenRequest
with an explicit client_id
ClientId
clientId
that, when used by a client, will then be considered an identified client.
var realtime = new Ably.Realtime({ key: 'xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-' });
realtime.auth.createTokenRequest({ clientId: 'Bob' }, function(err, tokenRequest) {
/* ... issue the TokenRequest to a client ... */
})
var realtime = new Ably.Realtime({ key: 'xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-' });
realtime.auth.createTokenRequest({ clientId: 'Bob' }, function(err, tokenRequest) {
/* ... issue the TokenRequest to a client ... */
})
realtime = Ably::Realtime.new(key: 'xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-')
realtime.auth.createTokenRequest(client_id: 'Bob') do |token_request|
# ... issue the TokenRequest to a client ...
end
ClientOptions options = new ClientOptions();
options.key = "xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-";
AblyRealtime realtime = new AblyRealtime(options);
TokenParams tokenParams = new TokenParams();
tokenParams.clientId = "Bob";
TokenRequest tokenRequest;
tokenRequest = realtime.auth.createTokenRequest(tokenParams, null);
/* ... issue the TokenRequest to a client ... */
AblyRealtime realtime = new AblyRealtime("xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-");
TokenParams tokenParams = new TokenParams {ClientId = "Bob"};
string tokenRequest = await realtime.Auth.CreateTokenRequestAsync(tokenParams);
/* ... issue the TokenRequest to a client ... */
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-"];
ARTTokenParams *tokenParams = [[ARTTokenParams alloc] initWithClientId:@"Bob"];
[realtime.auth createTokenRequest:tokenParams options:nil
callback:^(ARTTokenRequest *tokenRequest NSError *error) {
// ... issue the TokenRequest to a client ...
}];
let realtime = ARTRealtime(key: "xVLyHw.9HqX5A:DOJ-87x3Gt91pbU-")
let tokenParams = ARTTokenParams(clientId: "Bob")
realtime.auth.createTokenRequest(tokenParams, options: nil) { tokenRequest, error in
// ... issue the TokenRequest to a client ...
}
Auth API Reference
- Properties
- Methods
- Related types
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 ART
Auth
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_options
tokenParams
and authOptions
passed in as the new defaults, to be used for all subsequent implicit or explicit token requests.
Any token_params
and auth_options
tokenParams
and authOptions
objects passed in will entirely replace (as opposed to being merged with) the currently client library saved token_params
and auth_options
tokenParams
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_options
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 Ably TokenRequests
in order to implement an Ably Token request callback for use by other clients.
Both auth_options
and token_params
authOptions
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 instanced, or later updated with an explicit authorize
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 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 optionalARTTokenParams
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_options
tokenParams
and authOptions
.
Both auth_options
and token_params
authOptions
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 instanced, or later updated with an explicit authorize
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 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 ErrorInfo
NSError
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)")
}
Related types
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 instanced. 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 instanced. 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 instanced. 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 instanced. The following named keys and values can be added to the Associative Array:
ART
AuthOptions
is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instanced.
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 signedTokenRequest
; aTokenDetails
(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:Callable
TokenCallback
Proc
Func<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
; aTokenDetails
(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:String
Uri
NSURL
- authMethodAuthMethodauth_method:auth_method
-
GET
:get
The HTTP verb to use for the request, eitherGET
:get
orPOST
:post
Type:String
Symbol
HttpMethod
- authHeadersAuthHeadersauth_headers:auth_headers
- A set of key value pair headers to be added to any request made to the
authUrl
AuthUrl
. Useful when an application requires these to be added to validate the request or implement the response. If theauthHeaders
object contains anauthorization
key, thenwithCredentials
will be set on the xhr request.
Type:Object
Dict
Hash
Associative Array
Param []
Dictionary<string, string>
Map<String, String>
- authParamsAuthParams:auth_paramsauth_params
- A set of key value pair params to be added to any request made to the
authUrl
AuthUrl
. When theauthMethod
AuthMethod
isGET
, query params are added to the URL, whereas whenauthMethod
AuthMethod
isPOST
, 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:Object
Hash
Associative Array
Param[]
Dictionary<string, string>
NSArray<NSURLQueryItem *>
[NSURLQueryItem]/Array<NSURLQueryItem>
Map<String, String>
- 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 asauthUrl
AuthUrl
:auth_url
auth_url
orauthCallback
AuthCallbackauth_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, aTokenRequest
object, or token string (obtained from thetoken
Token
property of aTokenDetails
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 asauthUrl
AuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about Token authentication
Type:String
,TokenDetails
orTokenRequest
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-pwh7wLNIV5R3jniibDCIxWrku40dBtFR3Opo01MzAB7Lv-t8
Type:String
- expiresExpires
-
The time (in milliseconds since the epoch)The time at which this token expires
Type:Integer
Long Integer
DateTimeOffset
Time
NSDate
- issuedIssued
-
The time (in milliseconds since the epoch)The time at which this token was issued
Type:Integer
Long Integer
DateTimeOffset
Time
NSDate
- 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:String
Capability
- 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_jsonTokenDetails.fromMap
TokenDetails.fromJson(String json) → TokenDetailsTokenDetails.from_json(String json) → TokenDetailsTokenDetails.fromMap(Map<String, dynamic> map)
A static factory methodnamed constructor to create a TokenDetails
from a deserialized TokenDetails
-like object or a JSON stringified TokenDetails
map. 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
fromMap
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 stringifiedTokenDetails
.
Type:Object, String
- map
- a
TokenDetails
-like deserialized map.
Type:Map<String, dynamic>
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:
String
Capability
- clientIdClientIdclient_id:client_id
- A client ID, used for identifying this client when publishing messages or for presence purposes. The
clientId
client_id
ClientId
can be any non-empty string. This option is primarily intended to be used in situations where the library is instanced with a key; note that aclientId
client_id
ClientId
may also be implicit in a token used to instance the library; an error will be raised if aclientId
client_id
ClientId
specified here conflicts with theclientId
client_id
ClientId
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 thenonce
, is used to prevent requests for Ably Token from being replayed.
Type:Integer
Long Integer
Time
NSDate
DateTimeOffset
DateTime
- ttlTtl:ttl
-
1 hour Requested time to live for the Ably Token being created in millisecondsin secondsas a
NSTimeInterval
as aTimeSpan
. When omitted, the Ably REST API default of 60 minutes is applied by Ably
Type:Integer
(milliseconds)Integer
(seconds)NSTimeInterval
Long Integer
TimeSpan
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 AblyTokenRequest
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:Integer
TimeSpan
NSTimeInterval
- timestampTimestamp
- The timestamp of this request in milliseconds
Type:Integer
Long Integer
Time
DateTimeOffset
NSDate
- 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_jsonTokenRequest.fromMap
TokenRequest.fromJson(String json) → TokenRequestTokenRequest.from_json(String json) → TokenRequestTokenRequest.fromMap(Map<String, dynamic> map)
A static factory methodnamed constructor to create a TokenRequest
from a deserialized TokenRequest
-like object or a JSON stringified TokenRequest
/span>map. 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
fromMap
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 stringifiedTokenRequest
.
Type:Object, String
- map
- a
TokenRequest
-like deserialized map.
Type:Map<String, dynamic>
Returns
A TokenRequest
object