From 52b1b21f0e4ce17736d18da9bd19cc29456f023d Mon Sep 17 00:00:00 2001
From: Greg Holmes <iam@gregholmes.co.uk>
Date: Tue, 28 Oct 2025 11:50:59 +0000
Subject: [PATCH] Migrate REST SDK API spec Authentication page to MDX

---
 content/api/rest-sdk/authentication.textile   |  597 ---------
 .../docs/api/rest-sdk/authentication.mdx      | 1185 +++++++++++++++++
 2 files changed, 1185 insertions(+), 597 deletions(-)
 delete mode 100644 content/api/rest-sdk/authentication.textile
 create mode 100644 src/pages/docs/api/rest-sdk/authentication.mdx

diff --git a/content/api/rest-sdk/authentication.textile b/content/api/rest-sdk/authentication.textile
deleted file mode 100644
index a944f181bf..0000000000
--- a/content/api/rest-sdk/authentication.textile
+++ /dev/null
@@ -1,597 +0,0 @@
----
-title: Authentication
-meta_description: "Client Library SDK REST API Reference Authentication documentation."
-meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Authentication"
-section: api
-index: 60
-languages:
-  - javascript
-  - nodejs
-  - php
-  - python
-  - ruby
-  - java
-  - swift
-  - objc
-  - csharp
-  - go
-jump_to:
-  Help with:
-    - Tokens#tokens
-    - Auth object#auth-object
-  Auth API properties:
-    - clientId#client-id
-  Auth API methods:
-    - authorize
-    - createTokenRequest#create-token-request
-    - requestToken#request-token
-    - revokeTokens#revoke-tokens
-  Types:
-    - Related Types#related-types
-redirect_from:
-  - /docs/api/versions/v1.1/rest-sdk/authentication
-  - /docs/api/versions/v1.0/rest-sdk/authentication
-  - /docs/api/versions/v0.8/rest-sdk/authentication
----
-
-This is the Authentication API Reference.
-
-h2(#tokens). Tokens
-
-In the documentation, references to Ably-compatible tokens typically refer either to an Ably Token, or an "Ably JWT":#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":#request-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":#ably-jwt, this will be simply referring to a JWT which has been signed by an Ably private API key.
-
-h2(#auth-object). Auth object
-
-The principal use-case for the @Auth@ object is to create Ably "@TokenRequest@":#token-request objects with "createTokenRequest":#create-token-request or obtain "Ably Tokens":#token-details from Ably with "requestToken":#request-token, and then issue them to other "less trusted" clients. Typically, your servers should be the only devices to have a "private API key":/docs/auth#api-key, and this private API key is used to securely sign Ably "@TokenRequest@":#token-request objects or request "Ably Tokens":#token-details from Ably. Clients are then issued with these short-lived "Ably Tokens":#token-details or Ably "@TokenRequest@":#token-request 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 "<span lang="default">@authorize@</span><span lang="csharp">@Authorize@</span>":#authorize.
-
-The Auth object is available as the <span lang="java">"@auth@ field":/docs/api/rest-sdk#auth</span><span lang="default">"@auth@ property":/docs/api/rest-sdk#auth</span><span lang="csharp">"@Auth@ property":/docs/api/rest-sdk#auth</span><span lang="ruby">"@auth@ attribute":/docs/api/rest-sdk#auth</span> of an "Ably REST client instance":/docs/api/rest-sdk#constructor.
-
-h2(#properties).
-  default: Auth Properties
-  php: Ably\Auth Properties
-  java: io.ably.lib.rest.Auth Members
-  ruby: Ably::Auth Attributes
-  python: Auth Attributes
-  objc,swift: ARTAuth Properties
-
-The <span lang="objc,swift">@ART@</span>@Auth@ object exposes the following public <span lang="default">properties</span><span lang="ruby,python">attributes</span><span lang="java">members</span>:
-
-h6(#client-id).
-  default: clientId
-  ruby:    client_id
-  python:  client_id
-  csharp:  ClientId
-  go:      ClientID
-
-The client ID string, if any, configured for this client connection. See "identified clients":#identified-clients for more information on trusted client identifiers.
-
-h2(#methods).
-  default: Auth Methods
-  java: io.ably.lib.rest.Auth Methods
-  ruby: Ably::Auth Methods
-  php: Ably\Auth Methods
-  objc,swift: ARTAuth Methods
-
-h6(#authorize).
-  default: authorize
-  csharp,go: Authorize
-
-<a id="authorise"></a>
-
-bq(definition).
-  default: authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "TokenDetails":#token-details tokenDetails))
-  jsall:   authorize("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenDetails":#token-details>
-  ruby:    "TokenDetails":#token-details authorize("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options)
-  python:  "TokenDetails":#token-details authorize(token_params="TokenParams":#token-params, auth_options="AuthOptions":#auth-options)
-  php:     "TokenDetails":#token-details authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  java:    "TokenDetails":#token-details authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  csharp:  Task<TokenDetails> AuthorizeAsync("TokenParams":#token-params tokenParams = null, "AuthOptions":#auth-options options = null);
-  go:      "TokenDetails":#token-details Authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  swift,objc: authorize(tokenParams: "ARTTokenParams":#token-params?, authOptions: "ARTAuthOptions":#auth-options?, callback: ("ARTTokenDetails":#token-details?, NSError?) -> Void)
-
-Instructs the library to get a new token immediately using the specified <span lang="ruby,python">@token_params@ and @auth_options@</span><span lang="default">@tokenParams@ and @authOptions@</span><span lang="go,csharp">@TokenParams@ and @AuthOptions@</span> (or if none specified, the client library defaults). Also stores any <span lang="ruby,python">@token_params@ and @auth_options@</span><span lang="go,csharp">@TokenParams@ and @AuthOptions@</span><span lang="default">@tokenParams@ and @authOptions@</span> passed in as the new defaults, to be used for all subsequent implicit or explicit token requests.
-
-Any <span lang="ruby,python">@token_params@ and @auth_options@</span><span lang="go,csharp">@TokenParams@ and @AuthOptions@</span><span lang="default">@tokenParams@ and @authOptions@</span> objects passed in will entirely replace (as opposed to being merged with) the currently saved <span lang="ruby,python">@token_params@ and @auth_options@</span><span lang="default">@tokenParams@ and @authOptions@</span>.
-
-h4. Parameters
-
-- <span lang="ruby,python">token_params</span><span lang="go">TokenParams</span><span lang="default">tokenParams</span> := <span lang="default">an optional object containing the "Ably Token parameters":#token-params</span><span lang="java,go">an optional "@TokenParams@":#token-params object containing the token parameters</span><span lang="python">an optional Dict containing the "Ably Token parameters":#token-params</span><span lang="ruby">an optional set of key value pairs containing the "Ably Token parameters":#token-params</span><span lang="php">an optional set of key value pairs in an associative array containing the "Ably Token parameters":#token-params</span> for the authorization request<br>__Type: "@TokenParams@":#token-params__
-
-- <span lang="ruby,python">auth_options</span><span lang="go">AuthOptions</span><span lang="default">authOptions</span> := <span lang="default">an optional object containing the "authentication options":#auth-options</span><span lang="java,go">an optional "@AuthOptions@":#auth-options object containing the authentication options</span><span lang="python">an optional Dict containing the "authentication options":#auth-options</span><span lang="ruby">an optional set of key value pairs containing the "authentication options":#auth-options</span><span lang="php">an optional set of key value pairs in an associative array containing the "authentication options":#auth-options</span> for the authorization request<br>__Type: "@AuthOptions@":#auth-options__
-
-- <div lang="swift,objc">callback</div> := called with a "@ARTTokenDetails@":#token-details object or an error
-
-blang[jsall].
-  h4. Returns
-
-  Returns a promise.
-
-  On success, the promise is fulfilled with the a "@TokenDetails@":#token-details object containing the details of the new or existing "Ably Token":#token-details along with the @token@ string.
-
-  On failure to obtain an token, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
-
-blang[objc,swift].
-  h4. Callback result
-
-  On success, @tokenDetails@ contains a "@TokenDetails@":#token-details object containing the details of the new or existing "Ably Token":#token-details along with the @token@ string.
-
-  On failure to obtain an token, @err@ contains an <span lang="ruby">"@ErrorInfo@":#error-info</span><span lang="objc,swift">@NSError@</span> object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
-
-blang[java,ruby,php,python,go].
-  h4. Returns
-
-  On success, a "@TokenDetails@":#token-details 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@":#ably-exception.
-
-blang[csharp].
-  h4. Returns
-
-  The method is asynchronous and returns a @Task@ which needs to be awaited.
-
-  On success, a "@TokenDetails@":#token-details object containing the details of the new or existing token along with the @token@ string is returned.
-
-  Failure to obtain a token will raise an "@AblyException@":#ably-exception.
-
-h4. Example
-
-bc[jsall]. try {
-  const tokenDetails = await client.auth.authorize({ clientId: 'bob' });
-  console.log('Success; token: ' + tokenDetails.token);
-} catch (error) {
-  console.log('An error occurred; err = ' + error.message);
-}
-
-bc[java]. 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());
-}
-
-bc[csharp]. 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; err = " + e.Message);
-}
-
-bc[ruby]. token_details = client.auth.authorize(client_id: 'bob')
-puts "Success; token = #{token_details.token}"
-
-bc[python]. token_details = client.auth.authorize(token_params={'client_id': 'bob'})
-print("Success; token = " + str(token_details.token))
-
-bc[php]. $tokenDetails = $client->auth->authorize(array('clientId' => 'bob'));
-echo("Success; token = " . $tokenDetails->token);
-
-bc[objc]. 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);
-  }
-}];
-
-bc[swift]. 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)")
-}
-
-bc[go]. tokenParams := &ably.TokenParams{
-  ClientID: "Bob",
-}
-token, err := client.Auth.Authorize(tokenParams, &ably.AuthOptions{})
-if err != nil {
-  fmt.Println(err)
-}
-fmt.Println(token)
-
-h6(#create-token-request).
-  default: createTokenRequest
-  csharp,go:  CreateTokenRequest
-  ruby:    create_token_request
-  python:  create_token_request
-
-bq(definition).
-  default: createTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "TokenRequest":#token-request tokenRequest))
-  jsall:   createTokenRequest("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenRequest":#token-request>
-  ruby:    "TokenRequest":#token-request create_token_request("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options)
-  python:  "TokenRequest":#token-request create_token_request(token_params="TokenParams":#token-params, key_name=String, key_secret=String)
-  php:     "TokenRequest":#token-request createTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  java:    "TokenRequest":#token-request createTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  go:      "TokenRequest":#token-request CreateTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  csharp:  Task<TokenRequest> CreateTokenRequestAsync(TokenParams tokenParams = null, AuthOptions authOptions = null)
-  objc,swift: createTokenRequest(tokenParams: "ARTTokenParams":#token-params?, options: "ARTAuthOptions":#auth-options?, callback: ("ARTTokenRequest":#token-request?, NSError?) -> Void)
-
-Creates and signs an Ably "@TokenRequest@":#request-token based on the specified <span lang="ruby,python">@token_params@ and @auth_options@</span><span lang="go">@TokenParams@ and @AuthOptions@</span><span lang="default">@tokenParams@ and @authOptions@</span>. Note this can only be used when the "API @key@":/docs/auth#api-key value is available locally, due to it being required to sign the Ably "@TokenRequest@":#request-token. Otherwise, Ably "@TokenRequests@":#request-token must be obtained from the key owner. Use this to generate Ably "@TokenRequests@":#request-token in order to implement an "Ably Token":#token-details request callback for use by other clients.
-
-Both <span lang="ruby,python">@auth_options@ and @token_params@</span><span lang="go">@AuthOptions@ and @TokenParams@</span><span lang="default">@authOptions@ and @tokenParams@</span> are optional. When omitted or <span lang="default">@null@</span><span lang="java">@Null@</span><span lang="python">@None@</span><span lang="ruby,objc,swift,go">@nil@</span>, 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 "<span lang="default">@authorize@</span><span lang="csharp,go">@Authorize@</span>":#authorize request. Values passed in will be used instead of (rather than being merged with) the default values.
-
-To understand why an Ably "@TokenRequest@":#request-token may be issued to clients in favor of an "Ably Token":#token-details, see "Token Authentication explained":/docs/auth/token.
-
-h4. Parameters
-
-- <span lang="ruby,python">token_params</span><span lang="go">TokenParams</span><span lang="default">tokenParams</span> := <span lang="default">an optional object containing the "token parameters":#token-params</span><span lang="java">an optional "@TokenParams@":#token-params object containing the token parameters</span><span lang="python">an optional Dict containing the "token parameters":#token-params</span><span lang="ruby">an optional set of key value pairs containing the "token parameters":#token-params</span><span lang="php">an optional set of key value pairs in an associative array containing the "token parameters":#token-params</span> for the Ably "@TokenRequest@":#request-token<br>__Type: "@TokenParams@":#token-params__
-
-- <span lang="ruby">auth_options</span><span lang="python">[auth options]</span><span lang="go">AuthOptions</span><span lang="default">authOptions</span> := <span lang="default">an optional object containing the "authentication options":#auth-options</span><span lang="java">an optional "@TokenParams@":#auth-options object containing the authentication options</span><span lang="python">various keyword arguments with the "authentication options":#auth-options</span><span lang="ruby">an optional set of key value pairs containing the "authentication options":#auth-options</span><span lang="php">an optional set of key value pairs in an associative array containing the "authentication options":#auth-options</span><span lang="objc,swift">an optional "@ARTTokenParams@":#token-params containing the "authentication options":#auth-options</span> for the "Ably Token":#token-details Request<br>__Type: "@AuthOptions@":#auth-options__
-
-- <div lang="swift,objc">callback</div> := called with a "@ARTTokenRequest@":#token-request object or an error
-
-blang[jsall].
-  h4. Returns
-
-  Returns a promise.
-
-  On success, the promise is fulfilled with a "@TokenRequest@":#token-request JSON object.
-
-  On failure to issue a "@TokenRequest@":#token-request, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
-
-blang[objc,swift].
-  h4. Callback result
-
-  On success, @tokenRequest@ contains a "@TokenRequest@":#token-request JSON object.
-
-  On failure to issue a "@TokenRequest@":#token-request, @err@ contains an "@ErrorInfo@":#error-info object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
-
-blang[java,ruby,php,python,go].
-  h4. Returns
-
-  On success, a "@TokenRequest@":#token-request object is returned.
-
-  Failure to issue a "@TokenRequest@":#token-request will raise an "@AblyException@":#ably-exception.
-
-blang[csharp].
-  h4. Returns
-
-  The method is asynchronous and returns a @Task@ which needs to be awaited.
-
-  On success, a "@TokenRequest@":#token-request object is returned.
-
-  Failure to issue a "@TokenRequest@":#token-request will raise an "@AblyException@":#ably-exception.
-
-h4. Example
-
-bc[jsall]. try {
-  const tokenRequest = await client.auth.createTokenRequest({ clientId: 'bob' });
-  console.log('Success; token request = ' + tokenRequest);
-} catch (error) {
-  console.log('An error occurred; err = ' + error.message);
-}
-
-bc[java]. 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());
-}
-
-bc[csharp]. try
-{
-  TokenParams tokenParams = new TokenParams { ClientId = "bob" };
-  var tokenRequest = await client.Auth.CreateTokenRequestAsync(tokenParams);
-  Console.WriteLine("Success; token request issued");
-}
-catch (AblyException e)
-{
-  Console.WriteLine("An error occurred; err = " + e.Message);
-}
-
-bc[ruby]. token_request = client.auth.create_token_request(client_id: 'bob')
-puts "Success; token request = #{token_request}"
-
-bc[python]. token_request = client.auth.create_token_request(token_params={'client_id': 'bob'})
-print("Success; token request = ' + str(token_request))
-
-bc[php]. $tokenRequest = $client->auth->createTokenRequest(array('clientId' => 'bob'))
-echo("Success; token request = " . $tokenRequest);
-
-bc[objc]. 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);
-    }
-}];
-
-bc[swift]. 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)")
-}
-
-bc[go]. tokenParams := &ably.TokenParams{
-  ClientID: "Bob",
-}
-tokenRequest, err := client.Auth.CreateTokenRequest(tokenParams, &ably.AuthOptions{})
-if err != nil {
-  fmt.Println(err)
-}
-fmt.Println(tokenRequest)
-
-h6(#request-token).
-  default:  requestToken
-  ruby:     request_token
-  python:   request_token
-  csharp:   RequestToken
-  go:       RequestToken
-
-bq(definition).
-  default: requestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "TokenDetails":#token-details tokenDetails))
-  jsall:   requestToken("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenDetails":#token-details>
-  ruby:    "TokenDetails":#token-details request_token("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options)
-  python:  "TokenDetails":#token-details request_token(token_params="TokenParams":#token-params, key_name=String, key_secret=None, auth_callback=Lambda, auth_url=String, auth_method=String, auth_headers=Dict, auth_params=Dict, query_time=Boolean)
-  php:     "TokenDetails":#token-details requestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  csharp:  Task<TokenDetails> RequestTokenAsync(TokenParams tokenParams = null, AuthOptions options = null)
-  java:    "TokenDetails":#token-details requestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-  objc,swift: requestToken(tokenParams: "ARTTokenParams":#token-params?, withOptions: "ARTAuthOptions":#auth-options?, callback: ("ARTTokenDetails":#token-details?, NSError?) -> Void)
-  go: "TokenDetails":#token-details RequestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
-
-Calls the "<span lang="default">@requestToken@</span><span lang="csharp,go">@RequestToken@</span> REST API endpoint":/docs/api/rest-api#request-token to obtain an "Ably Token":#token-details according to the specified <span lang="ruby,python">@token_params@ and @auth_options@</span><span lang="default">@tokenParams@ and @authOptions@</span>.
-
-Both <span lang="ruby,python">@auth_options@ and @token_params@</span><span lang="default">@authOptions@ and @tokenParams@</span> are optional. When omitted or <span lang="default">@null@</span><span lang="java">@Null@</span><span lang="python">@None@</span><span lang="ruby,objc,swift,go">@nil@</span>, 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 "<span lang="default">@authorize@</span><span lang="csharp,go">@Authorize@</span>":#authorize request. Values passed in will be used instead of (rather than being merged with) the default values.
-
-To understand why an Ably "@TokenRequest@":#request-token may be issued to clients in favor of an "Ably Token":#token-details, see "Token Authentication explained":/docs/auth/token.
-
-h4. Parameters
-
-- <span lang="ruby,python">token_params</span><span lang="default">tokenParams</span> := <span lang="default">an optional object containing the "token parameters":#token-params</span><span lang="python">an optional Dict containing the "token parameters":#token-params</span><span lang="java">an optional "@TokenParams@":#token-params object containing the token parameters</span><span lang="ruby">an optional set of key value pairs containing the "token parameters":#token-params</span><span lang="php">an optional set of key value pairs in an associative array containing the "token parameters":#token-params</span> for the requested "Ably Token":#token-details<br>__Type: "@TokenParams@":#token-params__
-
-- <span lang="python">[auth options]</span><span lang="ruby">auth_options</span><span lang="default">authOptions</span> := <span lang="default">an optional object containing the "authentication options":#auth-options</span><span lang="python">various keyword arguments with the "authentication options":#auth-options</span><span lang="java">an optional "@TokenParams@":#auth-options object containing the authentication options</span><span lang="ruby">an optional set of key value pairs containing the "authentication options":#auth-options</span><span lang="php">an optional set of key value pairs in an associative array containing the "authentication options":#auth-options</span> for the requested "Ably Token":#token-details<br>__Type: "@AuthOptions@":#auth-options__
-
-- <div lang="swift,objc">callback</div> := called with a "@ARTTokenDetails@":#token-details object or an error
-
-blang[jsall].
-  h4. Returns
-
-  Returns a promise.
-
-  On success, the promise is fulfilled with a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string.
-
-  On failure to obtain an "Ably Token":#token-details, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
-
-blang[objc,swift].
-  h4. Callback result
-
-  On success, @tokenDetails@ contains a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string.
-
-  On failure to obtain an "Ably Token":#token-details, @err@ contains an <span lang="ruby">"@ErrorInfo@":#error-info</span><span lang="objc,swift">@NSError@</span> object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
-
-blang[java,ruby,php,python,go].
-  h4. Returns
-
-  On success, a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string is returned.
-
-  Failure to obtain an "Ably Token":#token-details will raise an "@AblyException@":#ably-exception.
-
-blang[csharp].
-  h4. Returns
-
-  The method is asynchronous and returns a @Task@ which needs to be awaited.
-
-  On success, a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string is returned.
-
-  Failure to obtain an "Ably Token":#token-details will raise an "@AblyException@":#ably-exception.
-
-h4. Example
-
-bc[jsall]. try {
-  const tokenDetails = await client.auth.requestToken({ clientId: 'bob'});
-  console.log('Success; token = ' + tokenDetails.token);
-} catch (error) {
-  console.log('An error occurred; err = ' + error.message);
-}
-
-bc[ruby]. token_details = client.auth.request_token(client_id: 'bob')
-puts "Success; token = #{token_details.token}"
-
-bc[python]. token_details = client.auth.request_token(token_params={'client_id': 'bob'})
-print("Success; token = " + str(token_details.token))
-
-bc[php]. $tokenDetails = $client->auth->requestToken(array('clientId' => 'bob'))
-echo("Success; token = " . $tokenDetails->token);
-
-bc[java]. 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());
-}
-
-bc[csharp]. try {
-  TokenParams tokenParams = new TokenParams { ClientId = "bob" };
-  var tokenDetails = await client.Auth.RequestTokenAsync(tokenParams);
-  Console.WriteLine("Success; token = " + tokenDetails.Token);
-}
-catch (AblyException e)
-{
-  Console.WriteLine("An error occurred; err = " + e.Message);
-}
-
-bc[objc]. 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);
-    }
-}];
-
-bc[swift]. 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)")
-}
-
-bc[go]. tokenParams := &ably.TokenParams{
-  ClientID: "Bob",
-}
-token, err := client.Auth.RequestToken(tokenParams, &ably.AuthOptions{})
-if err != nil {
-  fmt.Println(err)
-}
-fmt.Println(token)
-
-blang[jsall].
-
-  h6(#revoke-tokens).
-    jsall: revokeTokens
-
-  bq(definition).
-    jsall: revokeTokens("TokenRevocationTargetSpecifier[]":#token-revocation-target-specifier specifiers, "TokenRevocationOptions":#token-revocation-options options?): Promise<"BatchResult":#batch-result<"TokenRevocationSuccessResult":#token-revocation-success-result | "TokenRevocationFailureResult":#token-revocation-failure-result>>
-
-  Calls the "@revokeTokens@ REST API endpoint":/docs/api/rest-api#revoke-tokens to revoke tokens specified by the provided array of "TokenRevocationTargetSpecifier":#token-revocation-target-specifier.
-
-  Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. See the "token revocation docs":/docs/auth/revocation for more information.
-
-  h4. Parameters
-
-  - specifiers := an array of "TokenRevocationTargetSpecifier":#token-revocation-target-specifier objects<br>__Type: "@TokenRevocationTargetSpecifier[]@":#token-revocation-target-specifier__
-
-  - options := an optional set of options which are used to modify the revocation request<br>__Type: "@TokenRevocationOptions@":#token-revocation-options__
-
-  h4. Returns
-
-  Returns a promise.
-
-  On success, the promise is fulfilled with a "BatchResult":#batch-result containing information about the result of the token revocation request for each provided "TokenRevocationTargetSpecifier":#token-revocation-target-specifier.
-
-  On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
-
-  h4. Example
-
-  bc[jsall]. try {
-    const response = await client.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]);
-    console.log('Revocation successful; revoked tokens: ' + response.results.length);
-  } catch (error) {
-    console.log('An error occurred; err = ' + error.message);
-  }
-
-h2(#related-types). Related types
-
-h3(#auth-options).
-  default:   AuthOptions Object
-  ruby:      AuthOptions Hash
-  java:      io.ably.lib.rest.Auth.AuthOptions
-
-<%= partial partial_version('types/_auth_options') %>
-
-h3(#token-details).
-  default: TokenDetails Object
-  objc,swift: ARTTokenDetails
-  java:    io.ably.lib.types.TokenDetails
-  ruby:    Ably::Models::TokenDetails
-
-<%= partial partial_version('types/_token_details') %>
-
-h3(#token-params).
-  default:   TokenParams Object
-  objc,swift:   ARTTokenParams
-  ruby:      TokenParams Hash
-  java:      io.ably.lib.rest.Auth.TokenParams
-
-<%= partial partial_version('types/_token_params') %>
-
-h3(#token-request).
-  default:   TokenRequest Object
-  objc,swift:   ARTTokenRequest
-  ruby:      Ably::Models::TokenRequest
-  java:      io.ably.lib.rest.Auth.TokenRequest
-
-<%= partial partial_version('types/_token_request') %>
-
-h3(#ably-jwt). Ably JWT
-
-An Ably JWT is not strictly an Ably construct, rather it is a "JWT":https://jwt.io/ 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":#tokens
-** @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":/docs/auth#api-key using the signature algorithm HS256 (HMAC using the SHA-256 hash algorithm). View the "JSON Web Algorithms (JWA) specification":https://tools.ietf.org/html/rfc7518 for further information.
-
-We recommend you use one of the many "JWT libraries available for simplicity":https://jwt.io/ when creating your JWTs.
-
-The following is an example of creating an Ably JWT:
-
-```[javascript]
-  var header = {
-    "typ":"JWT",
-    "alg":"HS256",
-    "kid": "{{API_KEY_NAME}}"
-  };
-  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), "{{API_KEY_SECRET}}");
-  var ablyJwt = base64Header + "." + base64Claims + "." + signature;
-```
-
-*Note:* At present Ably does not support asymmetric signatures based on a keypair belonging to a third party.
-
-h3(#batch-result).
-  jsall: BatchResult
-
-blang[jsall].
-  <%= partial partial_version('types/_batch_result') %>
-
-h3(#token-revocation-target-specifier).
-  jsall: TokenRevocationTargetSpecifier
-
-blang[jsall].
-  <%= partial partial_version('types/_token_revocation_target_specifier') %>
-
-h3(#token-revocation-options).
-  jsall: TokenRevocationOptions
-
-blang[jsall].
-  <%= partial partial_version('types/_token_revocation_options') %>
-
-h3(#token-revocation-success-result).
-  jsall: TokenRevocationSuccessResult
-
-blang[jsall].
-  <%= partial partial_version('types/_token_revocation_success_result') %>
-
-h3(#token-revocation-failure-result).
-  jsall: TokenRevocationFailureResult
-
-blang[jsall].
-  <%= partial partial_version('types/_token_revocation_failure_result') %>
diff --git a/src/pages/docs/api/rest-sdk/authentication.mdx b/src/pages/docs/api/rest-sdk/authentication.mdx
new file mode 100644
index 0000000000..1f8922febb
--- /dev/null
+++ b/src/pages/docs/api/rest-sdk/authentication.mdx
@@ -0,0 +1,1185 @@
+---
+title: Authentication
+meta_description: "Client Library SDK REST API Reference Authentication documentation."
+meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Authentication"
+jump_to:
+  Help with:
+    - Tokens#tokens
+    - Auth object#auth-object
+  Auth API properties:
+    - clientId#client-id
+  Auth API methods:
+    - authorize
+    - createTokenRequest#create-token-request
+    - requestToken#request-token
+    - revokeTokens#revoke-tokens
+  Types:
+    - Related Types#related-types
+redirect_from:
+  - /docs/api/versions/v1.1/rest-sdk/authentication
+  - /docs/api/versions/v1.0/rest-sdk/authentication
+  - /docs/api/versions/v0.8/rest-sdk/authentication
+---
+
+This is the Authentication API Reference.
+
+## Tokens <a id="#tokens" />
+
+In the documentation, references to Ably-compatible tokens typically refer either to an Ably Token, or an [Ably JWT](#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](#request-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](#ably-jwt), this will be simply referring to a JWT which has been signed by an Ably private API key.
+
+## Auth object <a id="#auth-object" />
+
+The principal use-case for the `Auth` object is to create Ably [`TokenRequest`](#token-request) objects with [`createTokenRequest`](#create-token-request) or obtain [Ably Tokens](#token-details) from Ably with [`requestToken`](#request-token), and then issue them to other "less trusted" clients. Typically, your servers should be the only devices to have a [private API key](/docs/auth#api-key), and this private API key is used to securely sign Ably [`TokenRequest`](#token-request) objects or request [Ably Tokens](#token-details) from Ably. Clients are then issued with these short-lived [Ably Tokens](#token-details) or Ably [`TokenRequest`](#token-request) 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 <If lang="javascript,nodejs,php,python,ruby,objc,swift,go,java">[`authorize`](#authorize)</If><If lang="csharp">[`Authorize`](#authorize)</If>.
+
+The Auth object is available as the <If lang="java">[`auth` field](/docs/api/rest-sdk#auth)</If><If lang="javascript,nodejs,php,python,objc,swift,go">[`auth` property](/docs/api/rest-sdk#auth)</If><If lang="csharp">[`Auth` property](/docs/api/rest-sdk#auth)</If><If lang="ruby">[`auth` attribute](/docs/api/rest-sdk#auth)</If> of an [Ably REST client instance](/docs/api/rest-sdk#constructor).
+
+## <If lang="javascript,nodejs,csharp,go">Auth Properties</If><If lang="php">Ably\Auth Properties</If><If lang="java">io.ably.lib.rest.Auth Members</If><If lang="ruby">Ably::Auth Attributes</If><If lang="python">Auth Attributes</If><If lang="objc,swift">ARTAuth Properties</If> <a id="#properties" />
+
+The <If lang="objc,swift">`ART`</If>`Auth` object exposes the following public <If lang="javascript,nodejs,csharp,go,php">properties</If><If lang="ruby,python">attributes</If><If lang="java">members</If>:
+
+### <If lang="javascript,nodejs,php,java,objc,swift">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp">ClientId</If><If lang="go">ClientID</If> <a id="#client-id" />
+
+The client ID string, if any, configured for this client connection. See [identified clients](#identified-clients) for more information on trusted client identifiers.
+
+## <If lang="javascript,nodejs,csharp,python,go">Auth Methods</If><If lang="java">io.ably.lib.rest.Auth Methods</If><If lang="ruby">Ably::Auth Methods</If><If lang="php">Ably\Auth Methods</If><If lang="objc,swift">ARTAuth Methods</If> <a id="#methods" />
+
+### <If lang="javascript,nodejs,php,java,ruby,python,objc,swift">authorize</If><If lang="csharp,go">Authorize</If> <a id="#authorise" />
+
+<If lang="javascript,nodejs">
+
+`authorize(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise<TokenDetails>`
+
+</If>
+<If lang="ruby">
+
+`TokenDetails authorize(TokenParams token_params, AuthOptions auth_options)`
+
+</If>
+<If lang="python">
+
+`TokenDetails authorize(token_params=TokenParams, auth_options=AuthOptions)`
+
+</If>
+<If lang="php">
+
+`TokenDetails authorize(TokenParams $tokenParams, AuthOptions $authOptions)`
+
+</If>
+<If lang="java">
+
+`TokenDetails authorize(TokenParams tokenParams, AuthOptions authOptions)`
+
+</If>
+<If lang="csharp">
+
+`Task<TokenDetails> AuthorizeAsync(TokenParams tokenParams = null, AuthOptions options = null);`
+
+</If>
+<If lang="go">
+
+`TokenDetails Authorize(TokenParams tokenParams, AuthOptions authOptions)`
+
+</If>
+<If lang="objc,swift">
+
+`authorize(tokenParams: ARTTokenParams?, authOptions: ARTAuthOptions?, callback: (ARTTokenDetails?, NSError?) -> Void)`
+
+</If>
+
+Instructs the library to get a new token immediately using the specified <If lang="ruby,python">`token_params` and `auth_options`</If><If lang="javascript,nodejs,php,java,objc,swift">`tokenParams` and `authOptions`</If><If lang="go,csharp">`TokenParams` and `AuthOptions`</If> (or if none specified, the client library defaults). Also stores any <If lang="ruby,python">`token_params` and `auth_options`</If><If lang="javascript,nodejs,php,java,objc,swift">`tokenParams` and `authOptions`</If><If lang="go,csharp">`TokenParams` and `AuthOptions`</If> passed in as the new defaults, to be used for all subsequent implicit or explicit token requests.
+
+Any <If lang="ruby,python">`token_params` and `auth_options`</If><If lang="javascript,nodejs,php,java,objc,swift">`tokenParams` and `authOptions`</If><If lang="go,csharp">`TokenParams` and `AuthOptions`</If> objects passed in will entirely replace (as opposed to being merged with) the currently saved <If lang="ruby,python">`token_params` and `auth_options`</If><If lang="javascript,nodejs,php,java,objc,swift">`tokenParams` and `authOptions`</If>.
+
+#### Parameters
+
+<If lang="javascript,nodejs,php,java,ruby,python,go,csharp">
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| <If lang="ruby,python">token_params</If><If lang="javascript,nodejs,php,java">tokenParams</If><If lang="go,csharp">TokenParams</If> | <If lang="javascript,nodejs,php,java">An optional object containing the [Ably Token parameters](#token-params)</If><If lang="java,go">An optional [`TokenParams`](#token-params) object containing the token parameters</If><If lang="python">An optional Dict containing the [Ably Token parameters](#token-params)</If><If lang="ruby">An optional set of key value pairs containing the [Ably Token parameters](#token-params)</If><If lang="php">An optional set of key value pairs in an associative array containing the [Ably Token parameters](#token-params)</If> for the authorization request | [`TokenParams`](#token-params) |
+| <If lang="ruby,python">auth_options</If><If lang="javascript,nodejs,php,java">authOptions</If><If lang="go,csharp">AuthOptions</If> | <If lang="javascript,nodejs,php,java">An optional object containing the [authentication options](#auth-options)</If><If lang="java,go">An optional [`AuthOptions`](#auth-options) object containing the authentication options</If><If lang="python">An optional Dict containing the [authentication options](#auth-options)</If><If lang="ruby">An optional set of key value pairs containing the [authentication options](#auth-options)</If><If lang="php">An optional set of key value pairs in an associative array containing the [authentication options](#auth-options)</If> for the authorization request | [`AuthOptions`](#auth-options) |
+
+</If>
+<If lang="objc,swift">
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| tokenParams | An optional object containing the [Ably Token parameters](#token-params) for the authorization request | [`ARTTokenParams`](#token-params) |
+| authOptions | An optional object containing the [authentication options](#auth-options) for the authorization request | [`ARTAuthOptions`](#auth-options) |
+| callback | Called with a [`ARTTokenDetails`](#token-details) object or an error | Callback |
+
+</If>
+
+<If lang="javascript,nodejs">
+
+#### Returns
+
+Returns a promise.
+
+On success, the promise is fulfilled with the a [`TokenDetails`](#token-details) object containing the details of the new or existing [Ably Token](#token-details) along with the `token` string.
+
+On failure to obtain an token, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation.
+
+</If>
+<If lang="objc,swift">
+
+#### Callback result
+
+On success, `tokenDetails` contains a [`TokenDetails`](#token-details) object containing the details of the new or existing [Ably Token](#token-details) along with the `token` string.
+
+On failure to obtain an token, `err` contains an `NSError` object with an error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation.
+
+</If>
+<If lang="java,ruby,php,python,go">
+
+#### Returns
+
+On success, a [`TokenDetails`](#token-details) 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`](#ably-exception).
+
+</If>
+<If lang="csharp">
+
+#### Returns
+
+The method is asynchronous and returns a `Task` which needs to be awaited.
+
+On success, a [`TokenDetails`](#token-details) object containing the details of the new or existing token along with the `token` string is returned.
+
+Failure to obtain a token will raise an [`AblyException`](#ably-exception).
+
+</If>
+
+#### Example
+
+<If lang="javascript">
+
+<Code>
+```javascript
+try {
+  const tokenDetails = await client.auth.authorize({ clientId: 'bob' });
+  console.log('Success; token: ' + tokenDetails.token);
+} catch (error) {
+  console.log('An error occurred; err = ' + error.message);
+}
+```
+</Code>
+
+</If>
+<If lang="nodejs">
+
+<Code>
+```nodejs
+try {
+  const tokenDetails = await client.auth.authorize({ clientId: 'bob' });
+  console.log('Success; token: ' + tokenDetails.token);
+} catch (error) {
+  console.log('An error occurred; err = ' + error.message);
+}
+```
+</Code>
+
+</If>
+<If lang="java">
+
+<Code>
+```java
+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());
+}
+```
+</Code>
+
+</If>
+<If lang="csharp">
+
+<Code>
+```csharp
+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; err = " + e.Message);
+}
+```
+</Code>
+
+</If>
+<If lang="ruby">
+
+<Code>
+```ruby
+token_details = client.auth.authorize(client_id: 'bob')
+puts "Success; token = #{token_details.token}"
+```
+</Code>
+
+</If>
+<If lang="python">
+
+<Code>
+```python
+token_details = client.auth.authorize(token_params={'client_id': 'bob'})
+print("Success; token = " + str(token_details.token))
+```
+</Code>
+
+</If>
+<If lang="php">
+
+<Code>
+```php
+$tokenDetails = $client->auth->authorize(array('clientId' => 'bob'));
+echo("Success; token = " . $tokenDetails->token);
+```
+</Code>
+
+</If>
+<If lang="objc">
+
+<Code>
+```objc
+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);
+  }
+}];
+```
+</Code>
+
+</If>
+<If lang="swift">
+
+<Code>
+```swift
+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)")
+}
+```
+</Code>
+
+</If>
+<If lang="go">
+
+<Code>
+```go
+tokenParams := &ably.TokenParams{
+  ClientID: "Bob",
+}
+token, err := client.Auth.Authorize(tokenParams, &ably.AuthOptions{})
+if err != nil {
+  fmt.Println(err)
+}
+fmt.Println(token)
+```
+</Code>
+
+</If>
+
+### <If lang="javascript,nodejs,php,java,objc,swift">createTokenRequest</If><If lang="csharp,go">CreateTokenRequest</If><If lang="ruby,python">create_token_request</If> <a id="#create-token-request" />
+
+<If lang="javascript,nodejs">
+
+`createTokenRequest(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise<TokenRequest>`
+
+</If>
+<If lang="ruby">
+
+`TokenRequest create_token_request(TokenParams token_params, AuthOptions auth_options)`
+
+</If>
+<If lang="python">
+
+`TokenRequest create_token_request(token_params=TokenParams, key_name=String, key_secret=String)`
+
+</If>
+<If lang="php">
+
+`TokenRequest createTokenRequest(TokenParams $tokenParams, AuthOptions $authOptions)`
+
+</If>
+<If lang="java">
+
+`TokenRequest createTokenRequest(TokenParams tokenParams, AuthOptions authOptions)`
+
+</If>
+<If lang="go">
+
+`TokenRequest CreateTokenRequest(TokenParams tokenParams, AuthOptions authOptions)`
+
+</If>
+<If lang="csharp">
+
+`Task<TokenRequest> CreateTokenRequestAsync(TokenParams tokenParams = null, AuthOptions authOptions = null)`
+
+</If>
+<If lang="objc,swift">
+
+`createTokenRequest(tokenParams: ARTTokenParams?, options: ARTAuthOptions?, callback: (ARTTokenRequest?, NSError?) -> Void)`
+
+</If>
+
+Creates and signs an Ably [`TokenRequest`](#request-token) based on the specified <If lang="ruby,python">`token_params` and `auth_options`</If><If lang="javascript,nodejs,php,java,objc,swift">`tokenParams` and `authOptions`</If><If lang="go">`TokenParams` and `AuthOptions`</If><If lang="csharp">`tokenParams` and `authOptions`</If>. Note this can only be used when the [API `key`](/docs/auth#api-key) value is available locally, due to it being required to sign the Ably [`TokenRequest`](#request-token). Otherwise, Ably [`TokenRequests`](#request-token) must be obtained from the key owner. Use this to generate Ably [`TokenRequests`](#request-token) in order to implement an [Ably Token](#token-details) request callback for use by other clients.
+
+Both <If lang="ruby,python">`auth_options` and `token_params`</If><If lang="javascript,nodejs,php,java,objc,swift">`authOptions` and `tokenParams`</If><If lang="go">`AuthOptions` and `TokenParams`</If><If lang="csharp">`authOptions` and `tokenParams`</If> are optional. When omitted or <If lang="javascript,nodejs,php,objc,swift,csharp">`null`</If><If lang="java">`Null`</If><If lang="python">`None`</If><If lang="ruby,go">`nil`</If>, 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 <If lang="javascript,nodejs,php,java,ruby,python,objc,swift">[`authorize`](#authorize)</If><If lang="csharp,go">[`Authorize`](#authorize)</If> request. Values passed in will be used instead of (rather than being merged with) the default values.
+
+To understand why an Ably [`TokenRequest`](#request-token) may be issued to clients in favor of an [Ably Token](#token-details), see [Token Authentication explained](/docs/auth/token).
+
+#### Parameters
+
+<If lang="javascript,nodejs,php,java,ruby,python,go,csharp">
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| <If lang="ruby,python">token_params</If><If lang="javascript,nodejs,php,java">tokenParams</If><If lang="go,csharp">TokenParams</If> | <If lang="javascript,nodejs,php,java">An optional object containing the [token parameters](#token-params)</If><If lang="java">An optional [`TokenParams`](#token-params) object containing the token parameters</If><If lang="python">An optional Dict containing the [token parameters](#token-params)</If><If lang="ruby">An optional set of key value pairs containing the [token parameters](#token-params)</If><If lang="php">An optional set of key value pairs in an associative array containing the [token parameters](#token-params)</If><If lang="go,csharp">An optional [`TokenParams`](#token-params) object containing the token parameters</If> for the Ably [`TokenRequest`](#request-token) | [`TokenParams`](#token-params) |
+| <If lang="ruby">auth_options</If><If lang="python">[auth options]</If><If lang="javascript,nodejs,php,java">authOptions</If><If lang="go,csharp">AuthOptions</If> | <If lang="javascript,nodejs,php,java">An optional object containing the [authentication options](#auth-options)</If><If lang="java,go,csharp">An optional [`AuthOptions`](#auth-options) object containing the authentication options</If><If lang="python">Various keyword arguments with the [authentication options](#auth-options)</If><If lang="ruby">An optional set of key value pairs containing the [authentication options](#auth-options)</If><If lang="php">An optional set of key value pairs in an associative array containing the [authentication options](#auth-options)</If> for the [Ably Token](#token-details) Request | [`AuthOptions`](#auth-options) |
+
+</If>
+<If lang="objc,swift">
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| tokenParams | An optional object containing the [token parameters](#token-params) for the Ably [`TokenRequest`](#request-token) | [`ARTTokenParams`](#token-params) |
+| authOptions | An optional object containing the [authentication options](#auth-options) for the [Ably Token](#token-details) Request | [`ARTAuthOptions`](#auth-options) |
+| callback | Called with a [`ARTTokenRequest`](#token-request) object or an error | Callback |
+
+</If>
+
+<If lang="javascript,nodejs">
+
+#### Returns
+
+Returns a promise.
+
+On success, the promise is fulfilled with a [`TokenRequest`](#token-request) JSON object.
+
+On failure to issue a [`TokenRequest`](#token-request), the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation.
+
+</If>
+<If lang="objc,swift">
+
+#### Callback result
+
+On success, `tokenRequest` contains a [`TokenRequest`](#token-request) JSON object.
+
+On failure to issue a [`TokenRequest`](#token-request), `err` contains an [`ErrorInfo`](#error-info) object with an error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation.
+
+</If>
+<If lang="java,ruby,php,python,go">
+
+#### Returns
+
+On success, a [`TokenRequest`](#token-request) object is returned.
+
+Failure to issue a [`TokenRequest`](#token-request) will raise an [`AblyException`](#ably-exception).
+
+</If>
+<If lang="csharp">
+
+#### Returns
+
+The method is asynchronous and returns a `Task` which needs to be awaited.
+
+On success, a [`TokenRequest`](#token-request) object is returned.
+
+Failure to issue a [`TokenRequest`](#token-request) will raise an [`AblyException`](#ably-exception).
+
+</If>
+
+#### Example
+
+<If lang="javascript,nodejs">
+
+<Code>
+```javascript
+try {
+  const tokenRequest = await client.auth.createTokenRequest({ clientId: 'bob' });
+  console.log('Success; token request = ' + tokenRequest);
+} catch (error) {
+  console.log('An error occurred; err = ' + error.message);
+}
+```
+</Code>
+
+</If>
+<If lang="java">
+
+<Code>
+```java
+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());
+}
+```
+</Code>
+
+</If>
+<If lang="csharp">
+
+<Code>
+```csharp
+try
+{
+  TokenParams tokenParams = new TokenParams { ClientId = "bob" };
+  var tokenRequest = await client.Auth.CreateTokenRequestAsync(tokenParams);
+  Console.WriteLine("Success; token request issued");
+}
+catch (AblyException e)
+{
+  Console.WriteLine("An error occurred; err = " + e.Message);
+}
+```
+</Code>
+
+</If>
+<If lang="ruby">
+
+<Code>
+```ruby
+token_request = client.auth.create_token_request(client_id: 'bob')
+puts "Success; token request = #{token_request}"
+```
+</Code>
+
+</If>
+<If lang="python">
+
+<Code>
+```python
+token_request = client.auth.create_token_request(token_params={'client_id': 'bob'})
+print("Success; token request = ' + str(token_request))
+```
+</Code>
+
+</If>
+<If lang="php">
+
+<Code>
+```php
+$tokenRequest = $client->auth->createTokenRequest(array('clientId' => 'bob'))
+echo("Success; token request = " . $tokenRequest);
+```
+</Code>
+
+</If>
+<If lang="objc">
+
+<Code>
+```objc
+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);
+    }
+}];
+```
+</Code>
+
+</If>
+<If lang="swift">
+
+<Code>
+```swift
+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)")
+}
+```
+</Code>
+
+</If>
+<If lang="go">
+
+<Code>
+```go
+tokenParams := &ably.TokenParams{
+  ClientID: "Bob",
+}
+tokenRequest, err := client.Auth.CreateTokenRequest(tokenParams, &ably.AuthOptions{})
+if err != nil {
+  fmt.Println(err)
+}
+fmt.Println(tokenRequest)
+```
+</Code>
+
+</If>
+
+### <If lang="javascript,nodejs,php,java,objc,swift">requestToken</If><If lang="ruby,python">request_token</If><If lang="csharp,go">RequestToken</If> <a id="#request-token" />
+
+<If lang="javascript,nodejs">
+
+`requestToken(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise<TokenDetails>`
+
+</If>
+<If lang="ruby">
+
+`TokenDetails request_token(TokenParams token_params, AuthOptions auth_options)`
+
+</If>
+<If lang="python">
+
+`TokenDetails request_token(token_params=TokenParams, key_name=String, key_secret=None, auth_callback=Lambda, auth_url=String, auth_method=String, auth_headers=Dict, auth_params=Dict, query_time=Boolean)`
+
+</If>
+<If lang="php">
+
+`TokenDetails requestToken(TokenParams $tokenParams, AuthOptions $authOptions)`
+
+</If>
+<If lang="java">
+
+`TokenDetails requestToken(TokenParams tokenParams, AuthOptions authOptions)`
+
+</If>
+<If lang="csharp">
+
+`Task<TokenDetails> RequestTokenAsync(TokenParams tokenParams = null, AuthOptions options = null)`
+
+</If>
+<If lang="go">
+
+`TokenDetails RequestToken(TokenParams tokenParams, AuthOptions authOptions)`
+
+</If>
+<If lang="objc,swift">
+
+`requestToken(tokenParams: ARTTokenParams?, withOptions: ARTAuthOptions?, callback: (ARTTokenDetails?, NSError?) -> Void)`
+
+</If>
+
+Calls the <If lang="javascript,nodejs,php,java,ruby,python,objc,swift">[`requestToken` REST API endpoint](/docs/api/rest-api#request-token)</If><If lang="csharp,go">[`RequestToken` REST API endpoint](/docs/api/rest-api#request-token)</If> to obtain an [Ably Token](#token-details) according to the specified <If lang="ruby,python">`token_params` and `auth_options`</If><If lang="javascript,nodejs,php,java,objc,swift">`tokenParams` and `authOptions`</If><If lang="csharp,go">`tokenParams` and `authOptions`</If>.
+
+Both <If lang="ruby,python">`auth_options` and `token_params`</If><If lang="javascript,nodejs,php,java,objc,swift">`authOptions` and `tokenParams`</If><If lang="csharp,go">`authOptions` and `tokenParams`</If> are optional. When omitted or <If lang="javascript,nodejs,php,objc,swift">`null`</If><If lang="java">`Null`</If><If lang="python">`None`</If><If lang="ruby,go">`nil`</If><If lang="csharp">`null`</If>, 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 <If lang="javascript,nodejs,php,java,ruby,python,objc,swift">[`authorize`](#authorize)</If><If lang="csharp,go">[`Authorize`](#authorize)</If> request. Values passed in will be used instead of (rather than being merged with) the default values.
+
+To understand why an Ably [`TokenRequest`](#request-token) may be issued to clients in favor of an [Ably Token](#token-details), see [Token Authentication explained](/docs/auth/token).
+
+#### Parameters
+
+<If lang="javascript,nodejs,php,java,ruby,python,go,csharp">
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| <If lang="ruby,python">token_params</If><If lang="javascript,nodejs,php,java">tokenParams</If><If lang="go,csharp">tokenParams</If> | <If lang="javascript,nodejs,php,java">An optional object containing the [token parameters](#token-params)</If><If lang="python">An optional Dict containing the [token parameters](#token-params)</If><If lang="java">An optional [`TokenParams`](#token-params) object containing the token parameters</If><If lang="ruby">An optional set of key value pairs containing the [token parameters](#token-params)</If><If lang="php">An optional set of key value pairs in an associative array containing the [token parameters](#token-params)</If><If lang="go,csharp">An optional object containing the [token parameters](#token-params)</If> for the requested [Ably Token](#token-details) | [`TokenParams`](#token-params) |
+| <If lang="python">[auth options]</If><If lang="ruby">auth_options</If><If lang="javascript,nodejs,php,java,go,csharp">authOptions</If> | <If lang="javascript,nodejs,php,java">An optional object containing the [authentication options](#auth-options)</If><If lang="python">Various keyword arguments with the [authentication options](#auth-options)</If><If lang="java">An optional [`AuthOptions`](#auth-options) object containing the authentication options</If><If lang="ruby">An optional set of key value pairs containing the [authentication options](#auth-options)</If><If lang="php">An optional set of key value pairs in an associative array containing the [authentication options](#auth-options)</If><If lang="go,csharp">An optional object containing the [authentication options](#auth-options)</If> for the requested [Ably Token](#token-details) | [`AuthOptions`](#auth-options) |
+
+</If>
+<If lang="objc,swift">
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| tokenParams | An optional object containing the [token parameters](#token-params) for the requested [Ably Token](#token-details) | [`ARTTokenParams`](#token-params) |
+| authOptions | An optional object containing the [authentication options](#auth-options) for the requested [Ably Token](#token-details) | [`ARTAuthOptions`](#auth-options) |
+| callback | Called with a [`ARTTokenDetails`](#token-details) object or an error | Callback |
+
+</If>
+
+<If lang="javascript,nodejs">
+
+#### Returns
+
+Returns a promise.
+
+On success, the promise is fulfilled with a [`TokenDetails`](#token-details) object containing the details of the new [Ably Token](#token-details) along with the `token` string.
+
+On failure to obtain an [Ably Token](#token-details), the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation.
+
+</If>
+
+<If lang="objc,swift">
+#### Callback result
+
+On success, `tokenDetails` contains a [`TokenDetails`](#token-details) object containing the details of the new [Ably Token](#token-details) along with the `token` string.
+
+On failure to obtain an [Ably Token](#token-details), `err` contains an `NSError` object with an error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation.
+</If>
+
+<If lang="java,ruby,php,python,go">
+#### Returns
+
+On success, a [`TokenDetails`](#token-details) object containing the details of the new [Ably Token](#token-details) along with the `token` string is returned.
+
+Failure to obtain an [Ably Token](#token-details) will raise an [`AblyException`](#ably-exception).
+</If>
+
+<If lang="csharp">
+#### Returns
+
+The method is asynchronous and returns a `Task` which needs to be awaited.
+
+On success, a [`TokenDetails`](#token-details) object containing the details of the new [Ably Token](#token-details) along with the `token` string is returned.
+
+Failure to obtain an [Ably Token](#token-details) will raise an [`AblyException`](#ably-exception).
+</If>
+
+#### Example
+
+<If lang="javascript">
+
+<Code>
+```javascript
+try {
+  const tokenDetails = await client.auth.requestToken({ clientId: 'bob'});
+  console.log('Success; token = ' + tokenDetails.token);
+} catch (error) {
+  console.log('An error occurred; err = ' + error.message);
+}
+```
+</Code>
+
+</If>
+<If lang="nodejs">
+
+<Code>
+```nodejs
+try {
+  const tokenDetails = await client.auth.requestToken({ clientId: 'bob'});
+  console.log('Success; token = ' + tokenDetails.token);
+} catch (error) {
+  console.log('An error occurred; err = ' + error.message);
+}
+```
+</Code>
+
+</If>
+
+<If lang="ruby">
+
+<Code>
+```ruby
+token_details = client.auth.request_token(client_id: 'bob')
+puts "Success; token = #{token_details.token}"
+```
+</Code>
+
+</If>
+
+<If lang="python">
+
+<Code>
+```python
+token_details = client.auth.request_token(token_params={'client_id': 'bob'})
+print("Success; token = " + str(token_details.token))
+```
+</Code>
+
+</If>
+
+<If lang="php">
+
+<Code>
+```php
+$tokenDetails = $client->auth->requestToken(array('clientId' => 'bob'))
+echo("Success; token = " . $tokenDetails->token);
+```
+</Code>
+
+</If>
+
+<If lang="java">
+
+<Code>
+```java
+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());
+}
+```
+</Code>
+
+</If>
+
+<If lang="csharp">
+
+<Code>
+```csharp
+try {
+  TokenParams tokenParams = new TokenParams { ClientId = "bob" };
+  var tokenDetails = await client.Auth.RequestTokenAsync(tokenParams);
+  Console.WriteLine("Success; token = " + tokenDetails.Token);
+}
+catch (AblyException e)
+{
+  Console.WriteLine("An error occurred; err = " + e.Message);
+}
+```
+</Code>
+
+</If>
+
+<If lang="objc">
+
+<Code>
+```objc
+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);
+    }
+}];
+```
+</Code>
+
+</If>
+
+<If lang="swift">
+
+<Code>
+```swift
+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)")
+}
+```
+</Code>
+
+</If>
+
+<If lang="go">
+
+<Code>
+```go
+tokenParams := &ably.TokenParams{
+  ClientID: "Bob",
+}
+token, err := client.Auth.RequestToken(tokenParams, &ably.AuthOptions{})
+if err != nil {
+  fmt.Println(err)
+}
+fmt.Println(token)
+```
+</Code>
+
+</If>
+
+<If lang="javascript,nodejs">
+
+### revokeTokens <a id="#revoke-tokens" />
+
+`revokeTokens(TokenRevocationTargetSpecifier[] specifiers, TokenRevocationOptions options?): Promise<BatchResult<TokenRevocationSuccessResult | TokenRevocationFailureResult>>`
+
+Calls the [`revokeTokens` REST API endpoint](/docs/api/rest-api#revoke-tokens) to revoke tokens specified by the provided array of [`TokenRevocationTargetSpecifier`](#token-revocation-target-specifier).
+
+Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. See the [token revocation docs](/docs/auth/revocation) for more information.
+
+#### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| specifiers | an array of [`TokenRevocationTargetSpecifier`](#token-revocation-target-specifier) objects | [`TokenRevocationTargetSpecifier[]`](#token-revocation-target-specifier) |
+| options | an optional set of options which are used to modify the revocation request | [`TokenRevocationOptions`](#token-revocation-options) |
+
+#### Returns
+
+Returns a promise.
+
+On success, the promise is fulfilled with a [`BatchResult`](#batch-result) containing information about the result of the token revocation request for each provided [`TokenRevocationTargetSpecifier`](#token-revocation-target-specifier).
+
+On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation.
+
+#### Example
+
+<If lang="javascript">
+
+<Code>
+```javascript
+try {
+  const response = await client.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]);
+  console.log('Revocation successful; revoked tokens: ' + response.results.length);
+} catch (error) {
+  console.log('An error occurred; err = ' + error.message);
+}
+```
+</Code>
+
+</If>
+<If lang="nodejs">
+
+<Code>
+```nodejs
+try {
+  const response = await client.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]);
+  console.log('Revocation successful; revoked tokens: ' + response.results.length);
+} catch (error) {
+  console.log('An error occurred; err = ' + error.message);
+}
+```
+</Code>
+
+</If>
+</If>
+
+## Related types <a id="#related-types" />
+
+### <If lang="javascript,nodejs,csharp,objc,php,python,swift,go">AuthOptions Object</If><If lang="ruby">AuthOptions Hash</If><If lang="java">io.ably.lib.rest.Auth.AuthOptions</If> <a id="#auth-options" />
+
+<If lang="javascript,nodejs">
+`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/auth) 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:
+</If>
+
+<If lang="ruby">
+`AuthOptions` is a Hash object and is used when making [authentication](/docs/auth) 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:
+</If>
+
+<If lang="python">
+`AuthOptions` is a Dict and is used when making [authentication](/docs/auth) 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:
+</If>
+
+<If lang="php">
+`AuthOptions` is an Associative Array and is used when making [authentication](/docs/auth) 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:
+</If>
+
+<If lang="java,go">
+`AuthOptions` is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated.
+</If>
+
+<If lang="swift,objc">
+`ARTAuthOptions` is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated.
+</If>
+
+#### <If lang="javascript,nodejs,csharp,objc,php,swift,go">Properties</If><If lang="java">Members</If><If lang="ruby,python">Attributes</If>
+
+| Name | Description | Type |
+|------|-------------|------|
+| <If lang="javascript,nodejs,java,objc,php,swift">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,java,objc,php,swift">function</If><If lang="javascript,nodejs">function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))`</If><If lang="java">`TokenCallback` instance</If><If lang="python">callable (eg a lambda)</If><If lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</If><If lang="csharp,go">function</If> 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | <If lang="javascript,nodejs,java,objc,php,swift">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If><If lang="csharp">`Func<TokenParams, Task<object>>`</If><If lang="go">`Callable`</If><If lang="python">`Callable`</If> |
+| <If lang="javascript,nodejs,java,objc,php,swift">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">:auth_url</If><If lang="python">auth_url</If> | 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | <If lang="javascript,nodejs,java,php,ruby,python,go">`String`</If><If lang="csharp">`Uri`</If><If lang="swift,objc">`NSURL`</If> |
+| <If lang="javascript,nodejs,java,objc,php,swift">authMethod</If><If lang="csharp,go">AuthMethod</If><If lang="python">auth_method</If><If lang="ruby">:auth_method</If> | _<If lang="javascript,nodejs,csharp,java,objc,php,swift,go,python">`GET`</If><If lang="ruby">`:get`</If>_ The HTTP verb to use for the request, either <If lang="javascript,nodejs,csharp,java,objc,php,swift,go,python">`GET`</If><If lang="ruby">`:get`</If> or <If lang="javascript,nodejs,csharp,java,objc,php,swift,go,python">`POST`</If><If lang="ruby">`:post`</If> | <If lang="javascript,nodejs,java,objc,php,swift,go,python">`String`</If><If lang="ruby">`Symbol`</If><If lang="csharp">`HttpMethod`</If> |
+| <If lang="javascript,nodejs,java,objc,php,swift">authHeaders</If><If lang="csharp,go">AuthHeaders</If><If lang="python">auth_headers</If><If lang="ruby">:auth_headers</If> | A set of key value pair headers to be added to any request made to the <If lang="javascript,nodejs,java,objc,php,ruby,python,swift">authUrl</If><If lang="csharp">AuthUrl</If><If lang="go">AuthUrl</If>. Useful when an application requires these to be added to validate the request or implement the response. <If lang="javascript">If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request.</If> | <If lang="javascript,nodejs,objc,swift,go,csharp">`Object`</If><If lang="python">`Dict`</If><If lang="ruby">`Hash`</If><If lang="php">`Associative Array`</If><If lang="java">`Param []`</If><If lang="csharp">`Dictionary<string, string>`</If> |
+| <If lang="javascript,nodejs,java,objc,php,swift">authParams</If><If lang="csharp,go">AuthParams</If><If lang="ruby">:auth_params</If><If lang="python">auth_params</If> | A set of key value pair params to be added to any request made to the <If lang="javascript,nodejs,java,objc,php,ruby,python,swift">authUrl</If><If lang="csharp,go">AuthUrl</If>. When the <If lang="javascript,nodejs,java,objc,php,ruby,python,swift">authMethod</If><If lang="csharp,go">AuthMethod</If> is `GET`, query params are added to the URL, whereas when <If lang="javascript,nodejs,java,objc,php,ruby,python,swift">authMethod</If><If lang="csharp,go">AuthMethod</If> 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. | <If lang="javascript,nodejs,go">`Object`</If><If lang="ruby">`Hash`</If><If lang="php">`Associative Array`</If><If lang="java">`Param[]`</If><If lang="csharp">`Dictionary<string, string>`</If><If lang="objc">`NSArray<NSURLQueryItem *>`</If><If lang="swift">`[NSURLQueryItem]/Array<NSURLQueryItem>`</If><If lang="python">`Object`</If> |
+| <If lang="javascript,nodejs,java,objc,php,swift">tokenDetails</If><If lang="csharp,go">TokenDetails</If><If lang="python">token_details</If><If lang="ruby">:token_details</If> | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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 <If lang="javascript,nodejs,java,objc,php,swift">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If>. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| <If lang="javascript,nodejs,java,objc,php,swift">key</If><If lang="csharp,go">Key</If><If lang="ruby">:key</If><If lang="python">key</If> | Optionally the [API key](/docs/auth#api-key) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` |
+| <If lang="javascript,nodejs,java,objc,php,swift">queryTime</If><If lang="csharp,go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/auth/token), 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](https://en.wikipedia.org/wiki/Ntpd). 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. | `Boolean` |
+| <If lang="javascript,nodejs,java,objc,php,swift">token</If><If lang="csharp,go">Token</If><If lang="ruby">:token</If><If lang="python">token</If> | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the <If lang="javascript,nodejs,java,objc,php,swift">token</If><If lang="csharp,go">Token</If><If lang="python">token</If><If lang="ruby">token</If> property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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 <If lang="javascript,nodejs,java,objc,php,swift">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If>. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+
+### <If lang="javascript,nodejs,csharp,php,python,go">TokenDetails Object</If><If lang="objc,swift">ARTTokenDetails</If><If lang="java">io.ably.lib.types.TokenDetails</If><If lang="ruby">Ably::Models::TokenDetails</If> <a id="#token-details" />
+
+`TokenDetails` is a type providing details of Ably Token string and its associated metadata.
+
+#### <If lang="javascript,nodejs,csharp,objc,php,python,swift,go">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>
+
+| Name | Description | Type |
+|------|-------------|------|
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">token</If><If lang="csharp,go">Token</If> | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">expires</If><If lang="csharp,go">Expires</If> | <If lang="javascript,nodejs,csharp,java,php,python,go">The time (in milliseconds since the epoch)</If><If lang="ruby,objc,swift">The time</If> at which this token expires | <If lang="javascript,nodejs,php,python,ruby,go">`Integer`</If><If lang="java">`Long Integer`</If><If lang="csharp">`DateTimeOffset`</If><If lang="ruby">`Time`</If><If lang="objc,swift">`NSDate`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">issued</If><If lang="csharp,go">Issued</If> | <If lang="javascript,nodejs,csharp,java,php,python,go">The time (in milliseconds since the epoch)</If><If lang="ruby,objc,swift">The time</If> at which this token was issued | <If lang="javascript,nodejs,php,python,ruby,go">`Integer`</If><If lang="java">`Long Integer`</If><If lang="csharp">`DateTimeOffset`</If><If lang="ruby">`Time`</If><If lang="objc,swift">`NSDate`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">capability</If><If lang="csharp,go">Capability</If> | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | <If lang="javascript,nodejs,java,objc,php,python,ruby,swift,go">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp,go">ClientId</If> | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` |
+
+<If lang="ruby">
+### Methods
+
+| Name | Description | Type |
+|------|-------------|------|
+| expired? | True when the token has expired | `Boolean` |
+
+</If>
+
+<If lang="python">
+### Methods
+
+| Name | Description | Type |
+|------|-------------|------|
+| is_expired() | True when the token has expired | `Boolean` |
+
+</If>
+
+<If lang="csharp">
+### Methods
+
+| Name | Description | Type |
+|------|-------------|------|
+| IsValidToken() | True if the token has not expired | `Boolean` |
+
+</If>
+
+### TokenDetails constructors
+
+#### <If lang="javascript,nodejs,java,csharp,objc,php,python,swift,go">TokenDetails.fromJson</If><If lang="ruby">TokenDetails.from_json</If> <a id="#token-details-from-json" />
+
+<If lang="javascript,nodejs,java,csharp,objc,php,python,swift,go">
+`TokenDetails.fromJson(String json) -> TokenDetails`
+</If>
+
+<If lang="ruby">
+`TokenDetails.from_json(String json) -> TokenDetails`
+</If>
+
+A static factory method to create a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| json | a `TokenDetails`-like deserialized object or JSON stringified `TokenDetails` | `Object, String` |
+
+#### Returns
+
+A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object
+
+### <If lang="javascript,nodejs,csharp,php,python,go">TokenParams Object</If><If lang="objc,swift">ARTTokenParams</If><If lang="ruby">TokenParams Hash</If><If lang="java">io.ably.lib.rest.Auth.TokenParams</If> <a id="#token-params" />
+
+<If lang="javascript,nodejs">
+`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following attributes can be defined on the object:
+</If>
+
+<If lang="ruby">
+`TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following key symbol values can be added to the Hash:
+</If>
+
+<If lang="python">
+`TokenParams` is a Dict and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following keys-value pairs can be added to the Dict:
+</If>
+
+<If lang="php">
+`TokenParams` is an Associative Array and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following named keys and values can be added to the Associative Array:
+</If>
+
+<If lang="java,csharp,go">
+`TokenParams` is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details).
+</If>
+
+<If lang="objc,swift">
+`ARTTokenParams` is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details).
+</If>
+
+#### <If lang="javascript,nodejs,csharp,objc,php,swift,go">Properties</If><If lang="java">Members</If><If lang="ruby,python">Attributes</If>
+
+| Name | Description | Type |
+|------|-------------|------|
+| <If lang="javascript,nodejs,java,objc,php,python,swift">capability</If><If lang="csharp,go">Capability</If><If lang="ruby">:capability</If> | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) 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](/docs/auth/capabilities). | <If lang="javascript,nodejs,java,objc,php,python,ruby,swift,go">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="csharp,go">ClientId</If><If lang="python">client_id</If><If lang="ruby">:client_id</If> | A client ID, used for identifying this client when publishing messages or for presence purposes. The <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp,go">ClientId</If> 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 <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp,go">ClientId</If> may also be implicit in a token used to instantiate the library; an error will be raised if a <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp,go">ClientId</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp,go">ClientId</If> implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">nonce</If><If lang="csharp,go">Nonce</If><If lang="ruby">:nonce</If> | 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. | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">timestamp</If><If lang="csharp,go">Timestamp</If><If lang="ruby">:timestamp</If> | <If lang="javascript,nodejs,java,objc,php,python,go">The timestamp (in milliseconds since the epoch)</If><If lang="ruby,objc,swift,csharp">The timestamp</If> of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | <If lang="javascript,nodejs,php,python,go">`Integer`</If><If lang="java">`Long Integer`</If><If lang="ruby">`Time`</If><If lang="objc,swift">`NSDate`</If><If lang="csharp">`DateTimeOffset`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">ttl</If><If lang="csharp,go">Ttl</If><If lang="ruby">:ttl</If> | _1 hour_ Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created <If lang="javascript,nodejs,java,objc,php,python,go">in milliseconds</If><If lang="ruby">in seconds</If><If lang="objc,swift">as a `NSTimeInterval`</If><If lang="csharp,go">as a `TimeSpan`.</If> When omitted, the Ably REST API default of 60 minutes is applied by Ably | <If lang="javascript,nodejs,php,python,go">`Integer` (milliseconds)</If><If lang="ruby">`Integer` (seconds)</If><If lang="objc,swift">`NSTimeInterval`</If><If lang="java">`Long Integer`</If><If lang="csharp">`TimeSpan`</If> |
+
+### <If lang="javascript,nodejs,csharp,php,python,go">TokenRequest Object</If><If lang="objc,swift">ARTTokenRequest</If><If lang="ruby">Ably::Models::TokenRequest</If><If lang="java">io.ably.lib.rest.Auth.TokenRequest</If> <a id="#token-request" />
+
+`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using <If lang="javascript,nodejs,java,objc,php,python,swift,csharp,go">[Auth#requestToken](/docs/api/rest-sdk/authentication#request-token)</If><If lang="ruby">[Auth#request_token](/docs/api/rest-sdk/authentication#request-token)</If>
+
+#### <If lang="javascript,nodejs,csharp,objc,php,python,swift,go">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>
+
+| Name | Description | Type |
+|------|-------------|------|
+| <If lang="javascript,nodejs,java,objc,php,swift">keyName</If><If lang="ruby,python">key_name</If><If lang="csharp,go">KeyName</If> | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">ttl</If><If lang="csharp">Ttl</If> | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) <If lang="javascript,nodejs,java,objc,php,python,go">in milliseconds</If><If lang="ruby">in seconds</If><If lang="csharp,go">as a `TimeSpan`</If>. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | <If lang="javascript,nodejs,php,python,ruby,go">`Integer`</If><If lang="csharp">`TimeSpan`</If><If lang="swift,objc">`NSTimeInterval`</If><If lang="java">`Integer`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">timestamp</If><If lang="csharp,go">Timestamp</If> | The timestamp of this request<If lang="javascript,nodejs,java,objc,php,python,go"> in milliseconds</If> | <If lang="javascript,nodejs,php,python,go">`Integer`</If><If lang="java">`Long Integer`</If><If lang="ruby">`Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="swift,objc">`NSDate`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">capability</If><If lang="csharp,go">Capability</If> | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) 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](/docs/auth) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp,go">ClientId</If> | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">nonce</If><If lang="csharp,go">Nonce</If> | An opaque nonce string of at least 16 characters | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,ruby,swift">mac</If><If lang="csharp,go">Mac</If> | The Message Authentication Code for this request | `String` |
+
+### TokenRequest constructors
+
+#### <If lang="javascript,nodejs,java,csharp,objc,php,python,swift,go">TokenRequest.fromJson</If><If lang="ruby">TokenRequest.from_json</If> <a id="#token-request-from-json" />
+
+<If lang="javascript,nodejs,java,csharp,objc,php,python,swift,go">
+`TokenRequest.fromJson(String json) -> TokenRequest`
+</If>
+
+<If lang="ruby">
+`TokenRequest.from_json(String json) -> TokenRequest`
+</If>
+
+A static factory method to create a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) 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
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| json | a `TokenRequest`-like deserialized object or JSON stringified `TokenRequest` | `Object, String` |
+
+#### Returns
+
+A [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object
+
+### Ably JWT <a id="#ably-jwt" />
+
+An Ably JWT is not strictly an Ably construct, rather it is a [JWT](https://jwt.io/) 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](#tokens)
+  * `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](/docs/auth#api-key) using the signature algorithm HS256 (HMAC using the SHA-256 hash algorithm). View the [JSON Web Algorithms (JWA) specification](https://tools.ietf.org/html/rfc7518) for further information.
+
+We recommend you use one of the many [JWT libraries available for simplicity](https://jwt.io/) when creating your JWTs.
+
+<If lang="javascript,nodejs">
+
+The following is an example of creating an Ably JWT:
+
+<If lang="javascript">
+
+<Code>
+```javascript
+  var header = {
+    "typ":"JWT",
+    "alg":"HS256",
+    "kid": "{{API_KEY_NAME}}"
+  };
+  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), "{{API_KEY_SECRET}}");
+  var ablyJwt = base64Header + "." + base64Claims + "." + signature;
+```
+</Code>
+
+</If>
+<If lang="nodejs">
+
+<Code>
+```nodejs
+  var header = {
+    "typ":"JWT",
+    "alg":"HS256",
+    "kid": "{{API_KEY_NAME}}"
+  };
+  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), "{{API_KEY_SECRET}}");
+  var ablyJwt = base64Header + "." + base64Claims + "." + signature;
+```
+</Code>
+
+</If>
+
+*Note:* At present Ably does not support asymmetric signatures based on a keypair belonging to a third party.
+
+</If>
+<If lang="javascript,nodejs">
+
+### BatchResult <a id="#batch-result" />
+
+A `BatchResult` contains information about the results of a batch operation.
+
+#### Properties
+
+| Property | Description | Type |
+|----------|-------------|------|
+| successCount | The number of successful operations in the request | `Number` |
+| failureCount | The number of unsuccessful operations in the request | `Number` |
+| messages | An array of results for the batch operation (for example, an array of [`BatchPublishSuccessResult`](/docs/api/realtime-sdk/types#batch-publish-success-result) or [`BatchPublishFailureResult`](/docs/api/realtime-sdk/types#batch-publish-failure-result) for a channel batch publish request) | `Object[]` |
+
+<If lang="javascript,nodejs">
+
+### TokenRevocationTargetSpecifier <a id="#token-revocation-target-specifier" />
+
+A `TokenRevocationTargetSpecifier` describes which tokens should be affected by a token revocation request.
+
+</If>
+
+#### Properties
+
+| Property | Description | Type |
+|----------|-------------|------|
+| type | The type of token revocation target specifier. Valid values include `clientId`, `revocationKey` and `channel` | `String` |
+| value | The value of the token revocation target specifier | `String` |
+
+<If lang="javascript,nodejs">
+
+### TokenRevocationOptions <a id="#token-revocation-options" />
+
+A `TokenRevocationOptions` describes the additional options accepted by revoke tokens request.
+
+</If>
+
+#### Properties
+
+| Property | Description | Type |
+|----------|-------------|------|
+| issuedBefore | An optional Unix timestamp in milliseconds where only tokens issued before this time are revoked. The default is the current time. Requests with an `issuedBefore` in the future, or more than an hour in the past, will be rejected | `Number` |
+| allowReauthMargin | _false_ If true, permits a token renewal cycle to take place without needing established connections to be dropped, by postponing enforcement to 30 seconds in the future, and sending any existing connections a hint to obtain (and upgrade the connection to use) a new token. The default is `false`, meaning that the effect is near-immediate. | `Boolean` |
+
+<If lang="javascript,nodejs">
+
+### TokenRevocationSuccessResult <a id="#token-revocation-success-result" />
+
+A `TokenRevocationSuccessResult` contains information about the result of a successful token revocation request for a single target specifier.
+
+</If>
+
+#### Properties
+
+| Property | Description | Type |
+|----------|-------------|------|
+| target | The target specifier | `Number` |
+| appliesAt | The time at which the token revocation will take effect, as a Unix timestamp in milliseconds | `Number` |
+| issuedBefore | A Unix timestamp in milliseconds. Only tokens issued earlier than this time will be revoked | `Number` |
+
+<If lang="javascript,nodejs">
+
+### TokenRevocationFailureResult <a id="#token-revocation-failure-result" />
+
+A `TokenRevocationFailureResult` contains information about the result of an unsuccessful token revocation request for a single target specifier.
+
+</If>
+
+#### Properties
+
+| Property | Description | Type |
+|----------|-------------|------|
+| target | The target specifier | `String` |
+| error | Describes the reason for which token revocation failed for the given `target` as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) |
+
+</If>