diff --git a/src/data/nav/chat.ts b/src/data/nav/chat.ts
index ad8ca06013..077f5ecd7a 100644
--- a/src/data/nav/chat.ts
+++ b/src/data/nav/chat.ts
@@ -58,6 +58,10 @@ export default {
           name: 'SDK setup',
           link: '/docs/chat/setup',
         },
+        {
+          name: 'Authentication',
+          link: '/docs/chat/authentication',
+        },
         {
           name: 'Connections',
           link: '/docs/chat/connect',
diff --git a/src/data/nav/platform.ts b/src/data/nav/platform.ts
index ce1a3b6682..0428b84a06 100644
--- a/src/data/nav/platform.ts
+++ b/src/data/nav/platform.ts
@@ -301,6 +301,36 @@ export default {
         },
       ],
     },
+    {
+      name: 'Authentication',
+      pages: [
+        {
+          name: 'Overview',
+          link: '/docs/platform/auth',
+          index: true,
+        },
+        {
+          name: 'Basic auth',
+          link: '/docs/platform/auth/basic',
+        },
+        {
+          name: 'Token auth',
+          link: '/docs/platform/auth/token',
+        },
+        {
+          name: 'Token revocation',
+          link: '/docs/platform/auth/revocation',
+        },
+        {
+          name: 'Identified clients',
+          link: '/docs/platform/auth/identified-clients',
+        },
+        {
+          name: 'Capabilities',
+          link: '/docs/platform/auth/capabilities',
+        },
+      ],
+    },
     {
       name: 'Tools',
       pages: [
diff --git a/src/data/nav/pubsub.ts b/src/data/nav/pubsub.ts
index 649d00dd04..f56ef304d1 100644
--- a/src/data/nav/pubsub.ts
+++ b/src/data/nav/pubsub.ts
@@ -83,36 +83,6 @@ export default {
         },
       ],
     },
-    {
-      name: 'Authentication',
-      pages: [
-        {
-          name: 'Overview',
-          link: '/docs/auth',
-          index: true,
-        },
-        {
-          name: 'Basic auth',
-          link: '/docs/auth/basic',
-        },
-        {
-          name: 'Token auth',
-          link: '/docs/auth/token',
-        },
-        {
-          name: 'Token revocation',
-          link: '/docs/auth/revocation',
-        },
-        {
-          name: 'Identified clients',
-          link: '/docs/auth/identified-clients',
-        },
-        {
-          name: 'Capabilities',
-          link: '/docs/auth/capabilities',
-        },
-      ],
-    },
     {
       name: 'Connections',
       pages: [
diff --git a/src/data/nav/spaces.ts b/src/data/nav/spaces.ts
index bc53734db3..e230c99349 100644
--- a/src/data/nav/spaces.ts
+++ b/src/data/nav/spaces.ts
@@ -21,6 +21,10 @@ export default {
           name: 'SDK setup',
           link: '/docs/spaces/setup',
         },
+        {
+          name: 'Authentication',
+          link: '/docs/spaces/authentication',
+        },
         {
           name: 'React Hooks',
           link: '/docs/spaces/react',
diff --git a/src/pages/docs/api/realtime-sdk.mdx b/src/pages/docs/api/realtime-sdk.mdx
index 0c12de70ef..fa88b14b1a 100644
--- a/src/pages/docs/api/realtime-sdk.mdx
+++ b/src/pages/docs/api/realtime-sdk.mdx
@@ -10,7 +10,7 @@ redirect_from:
 
 ## Constructor <a id="constructor" />
 
-The Ably Realtime library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/auth/basic) or [Token](/docs/auth/token), as shown below:
+The Ably Realtime library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/platform/auth/basic) or [Token](/docs/platform/auth/token), as shown below:
 
 <If lang="javascript,nodejs">
 
@@ -116,13 +116,13 @@ The Realtime constructor is used to instantiate the library. The Realtime librar
 
 ### Authentication <a id="authentication" />
 
-The Realtime library needs to have credentials to be able to authenticate with the Ably service. Ably supports both Basic and Token based authentication schemes. Read more on [authentication](/docs/auth).
+The Realtime library needs to have credentials to be able to authenticate with the Ably service. Ably supports both Basic and Token based authentication schemes. Read more on [authentication](/docs/platform/auth).
 
 #### Basic Authentication
 
 <If lang="javascript,nodejs,ruby,java,swift,objc,flutter,csharp">
 
-You can pass a full-length API key in as `ClientOptions#key` (or just straight into the constructor instead of a `ClientOptions` instance), as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use [Basic authentication](/docs/auth/basic), or if you want to be able to [request Ably Tokens](/docs/auth/token) without needing to defer to a separate entity to sign [Ably TokenRequests](/docs/api/realtime-sdk/authentication#token-request). Note that initializing the library with a `key` does not necessarily mean that the library will use Basic auth; it is also able to create and sign Ably [TokenRequests](/docs/api/realtime-sdk/authentication#token-request), and can use token authentication for itself if it needs to or if [`ClientOptions#useTokenAuth`](#client-options) is enabled.
+You can pass a full-length API key in as `ClientOptions#key` (or just straight into the constructor instead of a `ClientOptions` instance), as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use [Basic authentication](/docs/platform/auth/basic), or if you want to be able to [request Ably Tokens](/docs/platform/auth/token) without needing to defer to a separate entity to sign [Ably TokenRequests](/docs/api/realtime-sdk/authentication#token-request). Note that initializing the library with a `key` does not necessarily mean that the library will use Basic auth; it is also able to create and sign Ably [TokenRequests](/docs/api/realtime-sdk/authentication#token-request), and can use token authentication for itself if it needs to or if [`ClientOptions#useTokenAuth`](#client-options) is enabled.
 
 </If>
 
@@ -146,7 +146,7 @@ The [`ClientOptions#token`](#client-options) option takes a `token` string or [t
 
 </If>
 
-Read more on [authentication](/docs/auth).
+Read more on [authentication](/docs/platform/auth).
 
 <If lang="objc,swift">
 
@@ -844,17 +844,17 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 
 | Property | Description |
 |----------|-------------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic)<br />**Type:** `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))` 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<br />**Type:** `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic)<br />**Type:** `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))` 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/platform/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Callable` |
 | authUrl | 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<br />**Type:** `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. 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><br />**Type:** `Object` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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<br />**Type:** `Object` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients)<br />**Type:** `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients)<br />**Type:** `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Type:** `Boolean`<br />**Default:** false |
@@ -869,7 +869,7 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 | transports | An optional array of transports to use, in descending order of preference. <If lang="javascript">In the browser environment the available transports are: `web_socket`, `xhr_polling`</If><If lang="nodejs">The transports available in the Node.js client library are: `web_socket`, `xhr_polling`, `comet`</If><br />**Type:** `String[]` |
 | recover | <If lang="javascript">This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See [connection state recovery](/docs/connect/states) for further information<br />**Type:** `String`, `Callable`</If><If lang="nodejs">This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code<br />**Type:** `String`</If> |
 | closeOnUnload | <If lang="javascript">When true, the client library will automatically send a close request to Ably whenever the `window beforeunload` event fires. By enabling this option, the close request sent to Ably ensures the connection state will not be retained and all channels associated with the connection will be detached. This is commonly used by developers who want presence leave events to fire immediately i.e. if a user navigates to another page or closes their browser, then enabling this option will result in the presence member leaving immediately. Without this option or an explicit call to the [`close`](/docs/api/realtime-sdk/connection#close) method of the [`Connection object`](/docs/api/realtime-sdk/connection), Ably expects that the abruptly disconnected connection could later be recovered and therefore does not immediately remove the user from presence. Instead, to avoid "twitchy" presence behavior an abruptly disconnected client is removed from channels in which they are present after 15 seconds, and the connection state is retained for two minutes<br />**Type:** `Boolean`<br />**Default:** true</If> |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |
@@ -881,17 +881,17 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 
 | Property | Description |
 |----------|-------------|
-| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic)<br />**Type:** `String` |
-| Token | An authenticated [`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 `Token` 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
-| AuthCallback | A function 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<br />**Type:** `Func<TokenParams, Task<object>>` |
+| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic)<br />**Type:** `String` |
+| Token | An authenticated [`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 `Token` 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/platform/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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
+| AuthCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Func<TokenParams, Task<object>>` |
 | AuthUrl | 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<br />**Type:** `Uri` |
 | AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `HttpMethod`<br />**Default:** `GET` |
 | AuthHeaders | A set of key value pair headers to be added to any request made to the `AuthUrl`. Useful when an application requires these to be added to validate the request or implement the response<br />**Type:** `Dictionary<string, string>` |
 | AuthParams | A set of key value pair params to be added to any request made to the `AuthUrl`. When the `AuthMethod` is `GET`, query params are added to the URL, whereas when `AuthMethod` 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<br />**Type:** `Dictionary<string, string>` |
-| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `TokenDetails` |
+| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `TokenDetails` |
 | Tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
-| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients)<br />**Type:** `String` |
-| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
+| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients)<br />**Type:** `String` |
+| UseTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
 | Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
 | Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
 | IdempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Type:** `Boolean`<br />**Default:** false |
@@ -904,7 +904,7 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 | EchoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
 | AutoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
 | Recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code<br />**Type:** `String` |
-| QueryTime | 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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
+| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
 | DefaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | DisconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
 | SuspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |
@@ -915,17 +915,17 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 
 | Property | Description |
 |----------|-------------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic)<br />**Type:** `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A `TokenCallback` instance 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<br />**Type:** `TokenCallback` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic)<br />**Type:** `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A `TokenCallback` instance 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/platform/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `TokenCallback` |
 | authUrl | 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<br />**Type:** `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response<br />**Type:** `Param[]` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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<br />**Type:** `Param[]` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients)<br />**Type:** `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients)<br />**Type:** `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** Null |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** Null |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Type:** `Boolean`<br />**Default:** false |
@@ -938,7 +938,7 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 | echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
 | autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
 | recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code<br />**Type:** `String` |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |
@@ -949,17 +949,17 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 
 | Property | Description |
 |----------|-------------|
-| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic)<br />**Type:** `String` |
-| :token | An authenticated [`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 :token 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 :auth_url or :auth_callback. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
-| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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<br />**Type:** `Proc` |
+| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic)<br />**Type:** `String` |
+| :token | An authenticated [`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 :token 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/platform/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 :auth_url or :auth_callback. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
+| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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/platform/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Proc` |
 | :auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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<br />**Type:** String |
 | :auth_method | The HTTP verb to use for the request, either `:get` or `:post`<br />**Type:** `Symbol`<br />**Default:** `:get` |
 | :auth_headers | A set of key value pair headers to be added to any request made to the :auth_url. Useful when an application requires these to be added to validate the request or implement the response<br />**Type:** `Hash` |
 | :auth_params | A set of key value pair params to be added to any request made to the :auth_url. When the :auth_method is `GET`, query params are added to the URL, whereas when :auth_method 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<br />**Type:** `Hash` |
-| :token_details | 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 :auth_url or :auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `TokenDetails` |
+| :token_details | 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 :auth_url or :auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `TokenDetails` |
 | :tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
-| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients)<br />**Type:** `String` |
-| :use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
+| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients)<br />**Type:** `String` |
+| :use_token_auth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
 | :endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
 | :environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
 | :idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Type:** `Boolean`<br />**Default:** false |
@@ -972,7 +972,7 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 | :echo_messages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
 | :auto_connect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
 | :recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recovery_key`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code<br />**Type:** `String` |
-| :query_time | 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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
+| :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
 | :default_token_params | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | :disconnected_retry_timeout | When the connection enters the `DISCONNECTED` state, after this delay in seconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** Integer<br />**Default:** 15s |
 | :suspended_retry_timeout | When the connection enters the `SUSPENDED` state, after this delay in seconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** Integer<br />**Default:** 30s |
@@ -983,17 +983,17 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 
 | Property | Description |
 |----------|-------------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic)<br />**Type:** `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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<br />**Type:** `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic)<br />**Type:** `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Callable` |
 | authUrl | 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<br />**Type:** `NSURL` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response<br />**Type:** `Object` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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<br />**Type:** `[NSURLQueryItem]/Array<NSURLQueryItem>` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients)<br />**Type:** `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients)<br />**Type:** `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Type:** `Boolean`<br />**Default:** false |
@@ -1007,7 +1007,7 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 | echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
 | autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
 | recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code<br />**Type:** `String` |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay as a `NSTimeInterval`, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 15,000ms |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay as a `NSTimeInterval`, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 30,000ms |
@@ -1018,17 +1018,17 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 
 | Property | Description |
 |----------|-------------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic)<br />**Type:** `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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<br />**Type:** `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic)<br />**Type:** `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Callable` |
 | authUrl | 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<br />**Type:** `NSURL` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response<br />**Type:** `Object` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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<br />**Type:** `NSArray<NSURLQueryItem *>` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients)<br />**Type:** `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients)<br />**Type:** `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** nil |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Type:** `Boolean`<br />**Default:** false |
@@ -1042,7 +1042,7 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 | echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
 | autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
 | recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code<br />**Type:** `String` |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay as a `NSTimeInterval`, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 15,000ms |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay as a `NSTimeInterval`, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `NSTimeInterval`<br />**Default:** 30,000ms |
@@ -1053,17 +1053,17 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 
 | Property | Description |
 |----------|-------------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic)<br />**Type:** `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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<br />**Type:** `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic)<br />**Type:** `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls<br />**Type:** `Callable` |
 | authUrl | 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<br />**Type:** `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Type:** `String`<br />**Default:** `GET` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response<br />**Type:** `Map<String, String>` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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<br />**Type:** `Map<String, String>` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token)<br />**Type:** `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token)<br />**Type:** `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Type:** `Boolean`<br />**Default:** true |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients)<br />**Type:** `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients)<br />**Type:** `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Type:** `Boolean`<br />**Default:** false |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Type:** `String`<br />**Default:** null |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Type:** `Boolean`<br />**Default:** false |
@@ -1073,7 +1073,7 @@ Returns a promise. On success, the promise is fulfilled with a [BatchResult](#ba
 | queueMessages | If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior allows applications to submit messages immediately upon instancing the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing under those conditions<br />**Type:** `Boolean`<br />**Default:** true |
 | echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Type:** `Boolean`<br />**Default:** true |
 | autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Type:** `Boolean`<br />**Default:** true |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Type:** `Boolean`<br />**Default:** false |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests<br />**Type:** [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 15,000ms |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Type:** `Integer`<br />**Default:** 30,000ms |
diff --git a/src/pages/docs/api/realtime-sdk/authentication.mdx b/src/pages/docs/api/realtime-sdk/authentication.mdx
index 54764aa625..46f200011c 100644
--- a/src/pages/docs/api/realtime-sdk/authentication.mdx
+++ b/src/pages/docs/api/realtime-sdk/authentication.mdx
@@ -29,7 +29,7 @@ In the documentation, references to Ably-compatible tokens typically refer eithe
 
 ## 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.
+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/platform/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,java,objc,ruby,swift">[`authorize`](#authorize)</If><If lang="csharp">[`Authorize`](#authorize)</If>.
 
@@ -41,7 +41,7 @@ The <If lang="objc,swift">`ART`</If>`Auth` object exposes the following public <
 
 ### <If lang="javascript,nodejs,java,objc,swift">clientId</If><If lang="ruby">client_id</If><If lang="csharp">ClientId</If> <a id="#client-id" />
 
-The client ID string, if any, configured for this client connection. See [identified clients](/docs/auth/identified-clients) for more information on trusted client identifiers.
+The client ID string, if any, configured for this client connection. See [identified clients](/docs/platform/auth/identified-clients) for more information on trusted client identifiers.
 
 ## <If lang="javascript,nodejs">Auth Methods</If><If lang="java">io.ably.lib.rest.Auth Methods</If><If lang="csharp">IO.Ably.AblyAuth Methods</If><If lang="ruby">Ably::Auth Methods</If><If lang="objc,swift">ARTAuth Methods</If> <a id="#methods" />
 
@@ -299,11 +299,11 @@ client.auth.authorize(tokenParams, options: nil) { tokenDetails, error in
 
 </If>
 
-Creates and signs an Ably [`TokenRequest`](#request-token) based on the specified (or if none specified, the client library stored) <If lang="ruby">`token_params` and `auth_options`</If><If lang="javascript,nodejs,java,csharp,objc,swift">`tokenParams` and `authOptions`</If>. Note this can only be used when the [API `key`](/docs/auth#api-key) value is available locally. Otherwise, the Ably [`TokenRequest`](#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.
+Creates and signs an Ably [`TokenRequest`](#request-token) based on the specified (or if none specified, the client library stored) <If lang="ruby">`token_params` and `auth_options`</If><If lang="javascript,nodejs,java,csharp,objc,swift">`tokenParams` and `authOptions`</If>. Note this can only be used when the [API `key`](/docs/platform/auth#api-key) value is available locally. Otherwise, the Ably [`TokenRequest`](#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">`auth_options` and `token_params`</If><If lang="javascript,nodejs,java,csharp,objc,swift">`authOptions` and `tokenParams`</If> are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the `ClientOptions` when the client library was instantiated, or later updated with an explicit <If lang="javascript,nodejs,java,objc,swift,ruby">[`authorize`](#authorize)</If><If lang="csharp">[`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 a token, see [Token Authentication explained](/docs/auth/token).
+To understand why an Ably [`TokenRequest`](#request-token) may be issued to clients in favor of a token, see [Token Authentication explained](/docs/platform/auth/token).
 
 #### Parameters
 
@@ -516,7 +516,7 @@ Calls the [`requestToken` REST API endpoint](/docs/api/rest-api#request-token) t
 
 Both <If lang="ruby">`auth_options` and `token_params`</If><If lang="javascript,nodejs,java,csharp,objc,swift">`authOptions` and `tokenParams`</If> are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the `ClientOptions` when the client library was instantiated, or later updated with an explicit <If lang="javascript,nodejs,java,objc,swift,ruby">[`authorize`](#authorize)</If><If lang="csharp">[`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 a token, see [Token Authentication explained](/docs/auth/token).
+To understand why an Ably [`TokenRequest`](#request-token) may be issued to clients in favor of a token, see [Token Authentication explained](/docs/platform/auth/token).
 
 #### Parameters
 
@@ -710,7 +710,7 @@ client.auth.requestToken(tokenParams, withOptions: : nil) { tokenDetails, error
 
 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.
+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/platform/auth/revocation) for more information.
 
 #### Parameters
 
@@ -767,25 +767,25 @@ try {
 
 <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:
+`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is a Hash object and is used when making [authentication](/docs/platform/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="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.
+`ARTAuthOptions` is used when making [authentication](/docs/platform/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated.
 
 </If>
 
 <If lang="java">
 
-`AuthOptions` is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated.
+`AuthOptions` is used when making [authentication](/docs/platform/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated.
 
 </If>
 
@@ -793,15 +793,15 @@ try {
 
 | Property | Description | Type |
 |----------|-------------|------|
-| <If lang="javascript,nodejs,java,objc,swift">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="ruby">:auth_callback</If> | A <If lang="objc,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="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</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,objc,swift">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If><If lang="csharp">`Func<TokenParams, Task<object>>`</If> |
+| <If lang="javascript,nodejs,java,objc,swift">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="ruby">:auth_callback</If> | A <If lang="objc,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="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | <If lang="javascript,nodejs,objc,swift">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If><If lang="csharp">`Func<TokenParams, Task<object>>`</If> |
 | <If lang="javascript,nodejs,java,objc,swift">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">: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">`String`</If><If lang="csharp">`Uri`</If><If lang="swift,objc">`NSURL`</If> |
 | <If lang="javascript,nodejs,java,objc,swift">authMethod</If><If lang="csharp">AuthMethod</If><If lang="ruby">:auth_method</If> | _<If lang="javascript,nodejs,java,objc,swift">`GET`</If><If lang="ruby">`:get`</If>_ The HTTP verb to use for the request, either <If lang="javascript,nodejs,java,objc,swift">`GET`</If><If lang="ruby">`:get`</If> or <If lang="javascript,nodejs,java,objc,swift">`POST`</If><If lang="ruby">`:post`</If> | <If lang="javascript,nodejs,java,objc,swift">`String`</If><If lang="ruby">`Symbol`</If><If lang="csharp">`HttpMethod`</If> |
 | <If lang="javascript,nodejs,objc,java,swift">authHeaders</If><If lang="csharp,go">AuthHeaders</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="nodejs,objc,swift,javascript">`authUrl`</If><If lang="csharp">`AuthUrl`</If>. Useful when an application requires these to be added to validate the request or implement the response. <If lang="javascript,nodejs">If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request.</If> | <If lang="javascript,nodejs,objc,swift">`Object`</If><If lang="ruby">`Hash`</If><If lang="java">`Param []`</If><If lang="csharp">`Dictionary<string, string>`</If> |
 | <If lang="javascript,nodejs,java,objc,swift">authParams</If><If lang="csharp">AuthParams</If><If lang="ruby">:auth_params</If> | A set of key value pair params to be added to any request made to the <If lang="javascript,nodejs">`authUrl`</If><If lang="csharp">`AuthUrl`</If>. When the <If lang="javascript,nodejs">`authMethod`</If><If lang="csharp">`AuthMethod`</If> is `GET`, query params are added to the URL, whereas when <If lang="javascript,nodejs">`authMethod`</If><If lang="csharpo">`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">`Object`</If><If lang="ruby">`Hash`</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="javascript,nodejs,java,objc,swift">tokenDetails</If><If lang="csharp,go">TokenDetails</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,swift">`authUrl`</If><If lang="csharp">`AuthUrl`</If><If lang="ruby">`:auth_url`</If> or <If lang="javascript,nodejs,java,objc,swift">`authCallback`</If><If lang="csharp">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,swift">key</If><If lang="csharp">Key</If><If lang="ruby">: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,swift">queryTime</If><If lang="csharp,go">QueryTime</If><If lang="ruby">: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,swift">token</If><If lang="csharp,go">Token</If><If lang="ruby">: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,swift">`token`</If><If lang="csharp,go">`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,swift">`authUrl`</If><If lang="csharp">AuthUrl</If><If lang="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,swift">authCallback</If><If lang="csharp">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,java,objc,swift">tokenDetails</If><If lang="csharp,go">TokenDetails</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,swift">`authUrl`</If><If lang="csharp">`AuthUrl`</If><If lang="ruby">`:auth_url`</If> or <If lang="javascript,nodejs,java,objc,swift">`authCallback`</If><If lang="csharp">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/platform/auth/token) | `TokenDetails` |
+| <If lang="javascript,nodejs,java,objc,swift">key</If><If lang="csharp">Key</If><If lang="ruby">:key</If> | Optionally the [API key](/docs/platform/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,swift">queryTime</If><If lang="csharp,go">QueryTime</If><If lang="ruby">:query_time</If> | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/platform/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,swift">token</If><If lang="csharp,go">Token</If><If lang="ruby">: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,swift">`token`</If><If lang="csharp,go">`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/platform/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,swift">`authUrl`</If><If lang="csharp">AuthUrl</If><If lang="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,swift">authCallback</If><If lang="csharp">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If>. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
 
 ### <If lang="javascript,nodejs">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><If lang="csharp">IO.Ably.TokenDetails</If> <a id="#token-details" />
 
@@ -814,8 +814,8 @@ try {
 | <If lang="javascript,nodejs,java,objc,swift,ruby">token</If><If lang="csharp">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,swift,ruby">expires</If><If lang="csharp">Expires</If> | <If lang="javascript,nodejs,java">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">`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,swift,ruby">issued</If><If lang="csharp">Issued</If> | <If lang="javascript,nodejs,java">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">`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,swift,ruby">capability</If><If lang="csharp">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,swift,ruby">`String`</If><If lang="csharp">`Capability`</If> |
-| <If lang="javascript,nodejs,java,objc,swift,flutter,php">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="javascript,nodejs,java,objc,swift,ruby">capability</If><If lang="csharp">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/platform/auth/capabilities) | <If lang="javascript,nodejs,java,objc,swift,ruby">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,java,objc,swift,flutter,php">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/platform/auth/identified-clients) | `String` |
 
 <If lang="ruby">
 
@@ -868,25 +868,25 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object
 
 <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:
+`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/platform/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="java,csharp">
 
-`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).
+`TokenParams` is used in the parameters of [token authentication](/docs/platform/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).
+`ARTTokenParams` is used in the parameters of [token authentication](/docs/platform/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details).
 
 </If>
 
@@ -894,8 +894,8 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object
 
 | Property | Description | Type |
 |----------|-------------|------|
-| <If lang="javascript,nodejs,java,objc,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,swift">`String`</If><If lang="csharp">`Capability`</If> |
-| <If lang="javascript,nodejs,java,objc,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,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,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,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,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,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/platform/auth/capabilities). | <If lang="javascript,nodejs,java,objc,swift">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,java,objc,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,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,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,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,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/platform/auth/identified-clients) | `String` |
 | <If lang="javascript,nodejs,java,objc,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,swift">timestamp</If><If lang="csharp">Timestamp</If><If lang="ruby">:timestamp</If> | <If lang="javascript,nodejs,java">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">`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="flutter">`DateTime`</If> |
 | <If lang="javascript,nodejs,java,objc,swift">ttl</If><If lang="csharp">Ttl</If><If lang="ruby">:ttl</If> | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created <If lang="javascript,nodejs,java">in milliseconds</If><If lang="ruby">in seconds</If><If lang="objc,swift">as a `NSTimeInterval`</If><If lang="csharp">as a `TimeSpan`.</If> When omitted, the Ably REST API default of 60 minutes is applied by Ably. <br />_Default: 1 hour_ | <If lang="javascript,nodejs">`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> |
@@ -911,7 +911,7 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object
 | <If lang="javascript,nodejs,java,objc,swift">keyName</If><If lang="ruby">key_name</If><If lang="csharp">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,swift,ruby">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,swift">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,java">`Integer`</If><If lang="csharp">`TimeSpan`</If><If lang="swift,objc">`NSTimeInterval`</If> |
 | <If lang="javascript,nodejs,java,ruby,objc,swift">timestamp</If><If lang="csharp">Timestamp</If> | The timestamp of this request<If lang="javascript,nodejs,java"> in milliseconds</If><If lang="ruby,csharp"></If> | <If lang="javascript,nodejs">`Integer`</If><If lang="java">`Long Integer`</If><If lang="ruby">`Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="swift,obj">`NSDate`</If> |
-| <If lang="javascript,nodejs,java,objc,swift,ruby">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,swift,ruby">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/platform/auth) | `String` |
 | <If lang="javascript,nodejs,java,objc,swift">clientId</If><If lang="ruby">client_id</If><If lang="csharp">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,swift,ruby">nonce</If><If lang="csharp">Nonce</If> | An opaque nonce string of at least 16 characters | `String` |
 | <If lang="javascript,nodejs,java,objc,swift,ruby">mac</If><If lang="csharp">Mac</If> | The Message Authentication Code for this request | `String` |
@@ -958,7 +958,7 @@ An Ably JWT is not strictly an Ably construct, rather it is a [JWT](https://jwt.
 
 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.
+The Ably JWT must be signed with the secret part of your [Ably API key](/docs/platform/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.
 
diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx
index d0e98f56d4..5e0cd9ffd9 100644
--- a/src/pages/docs/api/realtime-sdk/channels.mdx
+++ b/src/pages/docs/api/realtime-sdk/channels.mdx
@@ -830,7 +830,7 @@ Failure to retrieve the message history will trigger the `errback` callbacks of
 
 `getMessage(serialOrMessage: string | Message): Promise<Message>`
 
-Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities).
+Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/platform/auth/capabilities).
 
 See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information.
 
@@ -905,7 +905,7 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR
 
 `getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`
 
-Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities).
+Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/platform/auth/capabilities).
 
 See [updating and deleting messages: message versions](/docs/messages/updates-deletes#versions) for more information.
 
diff --git a/src/pages/docs/api/realtime-sdk/presence.mdx b/src/pages/docs/api/realtime-sdk/presence.mdx
index 5e04e9ac8f..11d5b37d8e 100644
--- a/src/pages/docs/api/realtime-sdk/presence.mdx
+++ b/src/pages/docs/api/realtime-sdk/presence.mdx
@@ -870,7 +870,7 @@ Unsubscribes all listeners to presence message events on this channel. This remo
 
 ### <If lang="javascript,nodejs,java,objc,swift">enterClient</If><If lang="ruby">enter_client</If><If lang="csharp">EnterClientAsync</If> <a id="enter-client" />
 
-Enter this presence channel for the given <If lang="flutter,javascript,nodejs,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If>. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#presence-multiple-client-id) for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an [API key](/docs/auth#api-keys,) or with a [token bound to a wildcard client ID](https://faqs.ably.com/can-a-client-emulate-any-client-id-i.e.-authenticate-using-a-wildcard-client-id.)
+Enter this presence channel for the given <If lang="flutter,javascript,nodejs,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If>. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#presence-multiple-client-id) for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an [API key](/docs/platform/auth#api-keys,) or with a [token bound to a wildcard client ID](https://faqs.ably.com/can-a-client-emulate-any-client-id-i.e.-authenticate-using-a-wildcard-client-id.)
 
 <If lang="flutter,ruby,java,swift,objc,csharp">
 
diff --git a/src/pages/docs/api/realtime-sdk/push-admin.mdx b/src/pages/docs/api/realtime-sdk/push-admin.mdx
index 53b8b171dd..917d36d660 100644
--- a/src/pages/docs/api/realtime-sdk/push-admin.mdx
+++ b/src/pages/docs/api/realtime-sdk/push-admin.mdx
@@ -27,7 +27,7 @@ The returned [`DeviceRegistrations`](#device-registrations-object) object provid
 
 #### <If lang="javascript,nodejs,java,objc,swift">channelSubscriptions</If><If lang="python,ruby">channel_subscriptions</If> <a id="channel-subscriptions" />
 
-The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object provides functionality for subscribing, listing and unsubscribing individual devices or groups of [identified devices](/docs/auth/identified-clients) to push notifications published on channels.
+The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object provides functionality for subscribing, listing and unsubscribing individual devices or groups of [identified devices](/docs/platform/auth/identified-clients) to push notifications published on channels.
 
 ### Methods <a id="methods" />
 
@@ -59,7 +59,7 @@ The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object pr
 
 </If>
 
-Publishes a push notification directly to a device or group of devices sharing a [client identifier](/docs/auth/identified-clients). See the [push notification direct publishing documentation](/docs/push/publish#direct-publishing) for more information.
+Publishes a push notification directly to a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients). See the [push notification direct publishing documentation](/docs/push/publish#direct-publishing) for more information.
 
 ##### Parameters
 
@@ -623,7 +623,7 @@ This object is accessible through <If lang="javascript,nodejs,java,python,objc,s
 
 </If>
 
-Retrieve all push channel subscriptions that match the provided params filter as a paginated list of [`PushChannelSubscription`](#push-channel-subscription) objects. Each [`PushChannelSubscription`](#push-channel-subscription) represents a device or set of devices sharing the same [client identifier](/docs/auth/identified-clients) registered to a channel to receive push notifications.
+Retrieve all push channel subscriptions that match the provided params filter as a paginated list of [`PushChannelSubscription`](#push-channel-subscription) objects. Each [`PushChannelSubscription`](#push-channel-subscription) represents a device or set of devices sharing the same [client identifier](/docs/platform/auth/identified-clients) registered to a channel to receive push notifications.
 
 ##### Parameters
 
@@ -796,7 +796,7 @@ Failure to retrieve the channels will trigger the `errback` callbacks of the [`D
 
 </If>
 
-Subscribe a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) for push notifications published on a channel.
+Subscribe a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) for push notifications published on a channel.
 
 ##### Parameters
 
@@ -849,7 +849,7 @@ On failure to create or update the channel subscription, `err` contains an [`Err
 
 </If>
 
-Unsubscribe a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) from push notifications on a channel. Requires `push-admin` permission or, in the case of a subscription associated with a given `deviceId`, `push-subscribe` permission together with device authentication matching that `deviceId`.
+Unsubscribe a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) from push notifications on a channel. Requires `push-admin` permission or, in the case of a subscription associated with a given `deviceId`, `push-subscribe` permission together with device authentication matching that `deviceId`.
 
 ##### Parameters
 
@@ -946,7 +946,7 @@ A `DeviceDetails` is a type encapsulating attributes of a device registered for
 | Property | Description | Type |
 |----------|------|-------------|
 | id | Unique identifier for the device generated by the device itself | `String` |
-| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Optional trusted [client identifier](/docs/auth/identified-clients) for the device | `String` |
+| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Optional trusted [client identifier](/docs/platform/auth/identified-clients) for the device | `String` |
 | <If lang="javascript,nodejs,java,python,objc,swift">formFactor</If><If lang="ruby">form_factor</If> | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` <If lang="java,ruby,python,objc,swift">or `embedded`</If><If lang="javascript,nodejs">`embedded` or `other`</If> | `String` |
 | metadata | Optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | <If lang="javascript,nodejs,java,python,objc,swift">`Object`</If><If lang="ruby">`Hash`</If> |
 | platform | Platform of the push device. Must be one of `ios` <If lang="java,ruby,python,objc,swift">or `android`</If><If lang="javascript,nodejs">`android` or `browser`</If> | `String` |
@@ -1140,7 +1140,7 @@ Failure to retrieve the message history will raise an [`AblyException`](/docs/ap
 
 ### <If lang="javascript,nodejs,python">PushChannelSubscription</If><If lang="objc,swift">ARTPushChannelSubscription</If><If lang="java">ChannelSubscription</If><If lang="ruby">Art::Models::PushChannelSubscription</If> <a id="push-channel-subscription" />
 
-An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications.
+An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) to a channel in order to receive push notifications.
 
 #### <If lang="javascript,nodejs,python,objc,swift">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>
 
@@ -1148,7 +1148,7 @@ An `PushChannelSubscription` is a type encapsulating the subscription of a devic
 |----------|------|-------------|
 | channel | The channel that this push notification subscription is associated with | `String` |
 | <If lang="javascript,nodejs,java,python,objc,swift">deviceId</If><If lang="ruby">device_id</If> | The device with this identifier is linked to this channel subscription. When present, <If lang="javascript,nodejs,java,python,objc,swift">`clientId`</If><If lang="ruby">`client_id`</If> is never present | `String` |
-| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, <If lang="javascript,nodejs,java,python,objc,swift">`deviceId`</If><If lang="ruby">`device_id`</If> is never present | `String` |
+| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/platform/auth/identified-clients) are included in this channel subscription. When present, <If lang="javascript,nodejs,java,python,objc,swift">`deviceId`</If><If lang="ruby">`device_id`</If> is never present | `String` |
 
 <If lang="java,python,objc,swift,ruby">
 
@@ -1193,14 +1193,14 @@ A [`PushChannelSubscription`](/docs/api/realtime-sdk/types#push-channel-subscrip
 
 </If>
 
-A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/auth/identified-clients).
+A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/platform/auth/identified-clients).
 
 ##### Parameters
 
 | Parameter | Description | Type |
 |-----------|------|-------------|
 | channel | Channel name linked to this push channel subscription | `String` |
-| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | `String` |
+| <If lang="javascript,nodejs,java,python,objc,swift">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/platform/auth/identified-clients) are included in the new push channel subscription | `String` |
 
 ##### Returns
 
diff --git a/src/pages/docs/api/realtime-sdk/push.mdx b/src/pages/docs/api/realtime-sdk/push.mdx
index 89196da0e7..8fbe075d93 100644
--- a/src/pages/docs/api/realtime-sdk/push.mdx
+++ b/src/pages/docs/api/realtime-sdk/push.mdx
@@ -124,7 +124,7 @@ A `DeviceDetails` is a type encapsulating attributes of a device registered for
 | Property | Description | Type |
 |----------|-------------|------|
 | id | Unique identifier for the device generated by the device itself | `String` |
-| clientId | Optional trusted [client identifier](/docs/auth/identified-clients) for the device | `String` |
+| clientId | Optional trusted [client identifier](/docs/platform/auth/identified-clients) for the device | `String` |
 | formFactor | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` <If lang="java,objc,swift">or `embedded`</If><If lang="javascript,nodejs">`embedded` or `other`</If> | `String` |
 | metadata | Optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | `Object` |
 | platform | Platform of the push device. Must be one of `ios` <If lang="java,objc,swift">or `android`</If><If lang="javascript,nodejs">`android` or `browser`</If> | `String` |
@@ -361,7 +361,7 @@ Failure to retrieve the message history will raise an [`AblyException`](/docs/ap
 
 ### <If lang="javascript,nodejs">PushChannelSubscription</If><If lang="java">ChannelSubscription</If><If lang="objc,swift">ARTPushChannelSubscription</If> <a id="push-channel-subscription" />
 
-A `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications.
+A `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) to a channel in order to receive push notifications.
 
 #### <If lang="javascript,nodejs,objc,swift">Properties</If><If lang="java">Members</If>
 
@@ -369,7 +369,7 @@ A `PushChannelSubscription` is a type encapsulating the subscription of a device
 |----------|-------------|------|
 | channel | The channel that this push notification subscription is associated with | `String` |
 | deviceId | The device with this identifier is linked to this channel subscription. When present, `clientId` is never present | `String` |
-| clientId | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `deviceId` is never present | `String` |
+| clientId | Devices with this [client identifier](/docs/platform/auth/identified-clients) are included in this channel subscription. When present, `deviceId` is never present | `String` |
 
 <If lang="java,objc,swift">
 
@@ -396,14 +396,14 @@ A [`PushChannelSubscription`](/docs/api/realtime-sdk/types#push-channel-subscrip
 
 `PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription`
 
-A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/auth/identified-clients).
+A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/platform/auth/identified-clients).
 
 ##### Parameters
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
 | channel | Channel name linked to this push channel subscription | `String` |
-| clientId | Devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | `String` |
+| clientId | Devices with this [client identifier](/docs/platform/auth/identified-clients) are included in the new push channel subscription | `String` |
 
 ##### Returns
 
diff --git a/src/pages/docs/api/realtime-sdk/types.mdx b/src/pages/docs/api/realtime-sdk/types.mdx
index 64452764e7..98a999da59 100644
--- a/src/pages/docs/api/realtime-sdk/types.mdx
+++ b/src/pages/docs/api/realtime-sdk/types.mdx
@@ -142,7 +142,7 @@ A `DeviceDetails` is a type encapsulating attributes of a device registered for
 | Property | Description | Type |
 |----------|-------------|------|
 | id | unique identifier for the device generated by the device itself | `String` |
-| <If lang="flutter">clientId</If><If lang="ruby">client_id</If> | optional trusted [client identifier](/docs/auth/identified-clients) for the device | `String` |
+| <If lang="flutter">clientId</If><If lang="ruby">client_id</If> | optional trusted [client identifier](/docs/platform/auth/identified-clients) for the device | `String` |
 | <If lang="flutter">formFactor</If><If lang="ruby">form_factor</If> | form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car`, or `embedded` | `String` |
 | metadata | optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | `Object` |
 | platform | platform of the push device. Must be one of `ios` or `android` | `String` |
@@ -1335,7 +1335,7 @@ Please note that `key` and `value` attributes are always strings. If an `Integer
 
 ### <If lang="javascript,nodejs">PushChannelSubscription</If><If lang="ruby">Ably::Models::PushChannelSubscription</If> <a id="push-channel-subscription" />
 
-An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications.
+An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) to a channel in order to receive push notifications.
 
 #### Properties
 
@@ -1343,7 +1343,7 @@ An `PushChannelSubscription` is a type encapsulating the subscription of a devic
 |----------|-------------|------|
 | channel | The channel that this push notification subscription is associated with | `String` |
 | <If lang="javascript,nodejs">deviceId</If><If lang="ruby">device_id</If> | The device with this identifier is linked to this channel subscription. When present, <If lang="javascript,nodejs">`clientId`</If><If lang="ruby">`client_id`</If> is never present | `String` |
-| <If lang="javascript,nodejs">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, <If lang="javascript,nodejs">`deviceId`</If><If lang="ruby">`device_id`</If> is never present | `String` |
+| <If lang="javascript,nodejs">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/platform/auth/identified-clients) are included in this channel subscription. When present, <If lang="javascript,nodejs">`deviceId`</If><If lang="ruby">`device_id`</If> is never present | `String` |
 
 </If>
 
@@ -1390,14 +1390,14 @@ A [`PushChannelSubscription`](/docs/api/realtime-sdk/types#push-channel-subscrip
 
 </If>
 
-A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/auth/identified-clients).
+A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/platform/auth/identified-clients).
 
 ##### Parameters
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
 | channel | Channel name linked to this push channel subscription | `String` |
-| <If lang="flutter,java,csharp,objc,swift,go">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | `String` |
+| <If lang="flutter,java,csharp,objc,swift,go">clientId</If><If lang="ruby">client_id</If> | Devices with this [client identifier](/docs/platform/auth/identified-clients) are included in the new push channel subscription | `String` |
 
 ##### Returns
 
@@ -1416,8 +1416,8 @@ A `PushChannelSubscription` object
 | <If lang="javascript,nodejs,java,objc,swift,ruby,flutter">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,swift,ruby,flutter">expires</If><If lang="csharp,go">Expires</If> | <If lang="javascript,nodejs,java,flutter,csharp,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,flutter">`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,swift,ruby,flutter">issued</If><If lang="csharp,go">Issued</If> | <If lang="javascript,nodejs,java,flutter,csharp,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,flutter">`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,swift,ruby,flutter">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,swift,ruby,flutter,go">`String`</If><If lang="csharp">`Capability`</If> |
-| <If lang="javascript,nodejs,java,objc,swift,flutter">clientId</If><If lang="ruby">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="javascript,nodejs,java,objc,swift,ruby,flutter">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/platform/auth/capabilities) | <If lang="javascript,nodejs,java,objc,swift,ruby,flutter,go">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,java,objc,swift,flutter">clientId</If><If lang="ruby">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/platform/auth/identified-clients) | `String` |
 
 <If lang="ruby">
 
@@ -1506,7 +1506,7 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object
 | <If lang="javascript,nodejs,java,objc,swift,flutter">keyName</If><If lang="ruby">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,swift,ruby,go,flutter">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,swift,flutter">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,java,ruby,go,flutter">`Integer`</If><If lang="csharp">`TimeSpan`</If><If lang="swift,objc">`NSTimeInterval`</If> |
 | <If lang="javascript,nodejs,java,objc,swift,ruby,flutter">timestamp</If><If lang="csharp,go">Timestamp</If> | The timestamp of this request<If lang="javascript,nodejs,java,objc,swift,flutter"> in milliseconds</If> | <If lang="javascript,nodejs,objc,swift,flutter">`Integer`</If><If lang="java">`Long Integer`</If><If lang="ruby">`Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="go">`Integer`</If> |
-| <If lang="javascript,nodejs,java,objc,swift,ruby,flutter">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,swift,ruby,flutter">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/platform/auth) | `String` |
 | <If lang="javascript,nodejs,java,objc,swift,flutter">clientId</If><If lang="ruby">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,swift,ruby,flutter">nonce</If><If lang="csharp,go">Nonce</If> | An opaque nonce string of at least 16 characters | `String` |
 | <If lang="javascript,nodejs,java,objc,swift,ruby,flutter">mac</If><If lang="csharp,go">Mac</If> | The Message Authentication Code for this request | `String` |
@@ -1836,19 +1836,19 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 <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:
+`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is a Hash object and is used when making [authentication](/docs/platform/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="java,swift,objc,go">
 
-<If lang="swift,objc">`ART`</If>`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 lang="swift,objc">`ART`</If>`AuthOptions` is used when making [authentication](/docs/platform/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated.
 
 </If>
 
@@ -1870,15 +1870,15 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| <If lang="javascript,nodejs,java,objc,swift,flutter">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,java,objc,swift,csharp,go,ruby,flutter">function</If><If lang="javascript,nodejs">function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))`</If><If lang="java">`TokenCallback` instance</If><If lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</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,objc,swift,flutter">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If><If lang="csharp">`Func<TokenParams, Task<object>>`</If> |
+| <If lang="javascript,nodejs,java,objc,swift,flutter">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,java,objc,swift,csharp,go,ruby,flutter">function</If><If lang="javascript,nodejs">function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))`</If><If lang="java">`TokenCallback` instance</If><If lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | <If lang="javascript,nodejs,objc,swift,flutter">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If><If lang="csharp">`Func<TokenParams, Task<object>>`</If> |
 | <If lang="javascript,nodejs,java,objc,swift,flutter">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">: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,go,flutter">`String`</If><If lang="csharp">`Uri`</If><If lang="swift,objc">`NSURL`</If><If lang="ruby">`String`</If> |
 | <If lang="javascript,nodejs,java,objc,swift,flutter">authMethod</If><If lang="csharp,go">AuthMethod</If><If lang="ruby">:auth_method</If> | _<If lang="javascript,nodejs,java,objc,swift,csharp,go,flutter">`GET`</If><If lang="ruby">`:get`</If>_ The HTTP verb to use for the request, either <If lang="javascript,nodejs,java,objc,swift,csharp,go,flutter">`GET`</If><If lang="ruby">`:get`</If> or <If lang="javascript,nodejs,java,objc,swift,csharp,go,flutter">`POST`</If><If lang="ruby">`:post`</If> | <If lang="javascript,nodejs,java,objc,swift,go,flutter">`String`</If><If lang="ruby">`Symbol`</If><If lang="csharp">`HttpMethod`</If> |
 | <If lang="javascript,nodejs,java,objc,swift,flutter">authHeaders</If><If lang="csharp,go">AuthHeaders</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,swift,flutter">authUrl</If><If lang="csharp">AuthUrl</If><If lang="ruby">:auth_url</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">`Object`</If><If lang="ruby">`Hash`</If><If lang="java">`Param[]`</If><If lang="csharp">`Dictionary<string, string>`</If><If lang="flutter">`Map<String, String>`</If> |
 | <If lang="javascript,nodejs,java,objc,swift,flutter">authParams</If><If lang="csharp,go">AuthParams</If><If lang="ruby">: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,swift,flutter">authUrl</If><If lang="csharp">AuthUrl</If><If lang="ruby">:auth_url</If>. When the <If lang="javascript,nodejs,java,objc,swift,flutter">authMethod</If><If lang="csharp,go">AuthMethod</If><If lang="ruby">:auth_method</If> is `GET`, query params are added to the URL, whereas when <If lang="javascript,nodejs,java,objc,swift,flutter">authMethod</If><If lang="csharp,go">AuthMethod</If><If lang="ruby">:auth_method</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">`Object`</If><If lang="ruby">`Hash`</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="flutter">`Map<String, String>`</If> |
-| <If lang="javascript,nodejs,java,objc,swift,flutter">tokenDetails</If><If lang="csharp,go">TokenDetails</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,swift,flutter">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">:auth_url</If> or <If lang="javascript,nodejs,java,objc,swift,flutter">authCallback</If><If lang="csharp,go">AuthCallback</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,swift,flutter">key</If><If lang="csharp,go">Key</If><If lang="ruby">: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,swift,flutter">queryTime</If><If lang="csharp,go">QueryTime</If><If lang="ruby">: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,swift,flutter">token</If><If lang="csharp,go">Token</If><If lang="ruby">: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,swift,flutter">token</If><If lang="csharp,go">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,swift,flutter">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">:auth_url</If> or <If lang="javascript,nodejs,java,objc,swift,flutter">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="ruby">:auth_callback</If>. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| <If lang="javascript,nodejs,java,objc,swift,flutter">tokenDetails</If><If lang="csharp,go">TokenDetails</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,swift,flutter">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">:auth_url</If> or <If lang="javascript,nodejs,java,objc,swift,flutter">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="ruby">:auth_callback</If>. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
+| <If lang="javascript,nodejs,java,objc,swift,flutter">key</If><If lang="csharp,go">Key</If><If lang="ruby">:key</If> | Optionally the [API key](/docs/platform/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,swift,flutter">queryTime</If><If lang="csharp,go">QueryTime</If><If lang="ruby">:query_time</If> | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/platform/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,swift,flutter">token</If><If lang="csharp,go">Token</If><If lang="ruby">: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,swift,flutter">token</If><If lang="csharp,go">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/platform/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,swift,flutter">authUrl</If><If lang="csharp,go">AuthUrl</If><If lang="ruby">:auth_url</If> or <If lang="javascript,nodejs,java,objc,swift,flutter">authCallback</If><If lang="csharp,go">AuthCallback</If><If lang="ruby">:auth_callback</If>. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
 
 ### <If lang="javascript,nodejs,flutter,go">ClientOptions Object</If><If lang="objc,swift">ARTClientOptions</If><If lang="ruby">ClientOptions Hash</If><If lang="java">io.ably.types.ClientOptions</If><If lang="csharp">IO.Ably.ClientOptions</If> <a id="client-options" />
 
@@ -1919,17 +1919,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))` 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 | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))` 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/platform/auth) for details of the Ably TokenRequest format and associated API calls | `Callable` |
 | authUrl | 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 | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Default:** `GET` | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. 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> | `Object` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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 | `Object` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Default:** true | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Default:** false | `Boolean` |
@@ -1944,7 +1944,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | transports | An optional array of transports to use, in descending order of preference. <If lang="javascript">In the browser environment the available transports are: `web_socket`, `xhr_polling`</If><If lang="nodejs">The transports available in the Node.js client library are: `web_socket`, `xhr_polling`, `comet`</If> | `String[]` |
 | recover | <If lang="javascript">This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See [connection state recovery](/docs/connect/states) for further information</If><If lang="nodejs">This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code</If> | <If lang="javascript">`String`, `Callable`</If><If lang="nodejs">`String`</If> |
 | closeOnUnload | <If lang="javascript">When true, the client library will automatically send a close request to Ably whenever the `window beforeunload` event fires. By enabling this option, the close request sent to Ably ensures the connection state will not be retained and all channels associated with the connection will be detached. This is commonly used by developers who want presence leave events to fire immediately i.e. if a user navigates to another page or closes their browser, then enabling this option will result in the presence member leaving immediately. Without this option or an explicit call to the [`close`](/docs/api/realtime-sdk/connection#close) method of the [`Connection object`](/docs/api/realtime-sdk/connection), Ably expects that the abruptly disconnected connection could later be recovered and therefore does not immediately remove the user from presence. Instead, to avoid "twitchy" presence behavior an abruptly disconnected client is removed from channels in which they are present after 15 seconds, and the connection state is retained for two minutes<br />**Default:** true</If> | `Boolean` |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Default:** 15,000ms | `Integer` |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Default:** 30,000ms | `Integer` |
@@ -1956,17 +1956,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| Token | An authenticated [`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 `Token` 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| AuthCallback | A function 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 | `Func<TokenParams, Task<object>>` |
+| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| Token | An authenticated [`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 `Token` 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/platform/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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| AuthCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls | `Func<TokenParams, Task<object>>` |
 | AuthUrl | 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 | `Uri` |
 | AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Default:** `GET` | `HttpMethod` |
 | AuthHeaders | A set of key value pair headers to be added to any request made to the `AuthUrl`. Useful when an application requires these to be added to validate the request or implement the response | `Dictionary<string, string>` |
 | AuthParams | A set of key value pair params to be added to any request made to the `AuthUrl`. When the `AuthMethod` is `GET`, query params are added to the URL, whereas when `AuthMethod` 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 | `Dictionary<string, string>` |
-| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | Tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Default:** true | `Boolean` |
-| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
+| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| UseTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
 | Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | IdempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Default:** false | `Boolean` |
@@ -1979,7 +1979,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | EchoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Default:** true | `Boolean` |
 | AutoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Default:** true | `Boolean` |
 | Recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code | `String` |
-| QueryTime | 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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
+| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
 | DefaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | DisconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Default:** 15,000ms | `Integer` |
 | SuspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Default:** 30,000ms | `Integer` |
@@ -1990,17 +1990,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A `TokenCallback` instance 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 | `TokenCallback` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A `TokenCallback` instance 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/platform/auth) for details of the Ably TokenRequest format and associated API calls | `TokenCallback` |
 | authUrl | 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 | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Default:** `GET` | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `Param[]` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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 | `Param[]` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Default:** true | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** Null | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** Null | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Default:** false | `Boolean` |
@@ -2013,7 +2013,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Default:** true | `Boolean` |
 | autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Default:** true | `Boolean` |
 | recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code | `String` |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Default:** 15,000ms | `Integer` |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Default:** 30,000ms | `Integer` |
@@ -2024,17 +2024,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| :token | An authenticated [`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 :token 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 :auth_url or :auth_callback. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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 | `Proc` |
+| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| :token | An authenticated [`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 :token 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/platform/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 :auth_url or :auth_callback. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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/platform/auth) for details of the Ably TokenRequest format and associated API calls | `Proc` |
 | :auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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 | `String` |
 | :auth_method | The HTTP verb to use for the request, either `:get` or `:post`<br />**Default:** `:get` | `Symbol` |
 | :auth_headers | A set of key value pair headers to be added to any request made to the :auth_url. Useful when an application requires these to be added to validate the request or implement the response | `Hash` |
 | :auth_params | A set of key value pair params to be added to any request made to the :auth_url. When the :auth_method is `GET`, query params are added to the URL, whereas when :auth_method 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 | `Hash` |
-| :token_details | 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 :auth_url or :auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| :token_details | 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 :auth_url or :auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | :tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Default:** true | `Boolean` |
-| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| :use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
+| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| :use_token_auth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
 | :endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** nil | `String` |
 | :environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** nil | `String` |
 | :idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Default:** false | `Boolean` |
@@ -2047,7 +2047,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | :echo_messages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Default:** true | `Boolean` |
 | :auto_connect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Default:** true | `Boolean` |
 | :recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recovery_key`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code | `String` |
-| :query_time | 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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
+| :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
 | :default_token_params | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | :disconnected_retry_timeout | When the connection enters the `DISCONNECTED` state, after this delay in seconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Default:** 15s | `Integer` |
 | :suspended_retry_timeout | When the connection enters the `SUSPENDED` state, after this delay in seconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Default:** 30s | `Integer` |
@@ -2058,17 +2058,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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 | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls | `Callable` |
 | authUrl | 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 | `NSURL` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Default:** `GET` | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `Object` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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 | `[NSURLQueryItem]/Array<NSURLQueryItem>` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Default:** true | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** nil | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** nil | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Default:** false | `Boolean` |
@@ -2082,7 +2082,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Default:** true | `Boolean` |
 | autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Default:** true | `Boolean` |
 | recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code | `String` |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay as a `NSTimeInterval`, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Default:** 15,000ms | `NSTimeInterval` |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay as a `NSTimeInterval`, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Default:** 30,000ms | `NSTimeInterval` |
@@ -2093,17 +2093,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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 | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls | `Callable` |
 | authUrl | 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 | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Default:** `GET` | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `Map<String, String>` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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 | `Map<String, String>` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Default:** true | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Default:** false | `Boolean` |
@@ -2113,7 +2113,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | queueMessages | If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior allows applications to submit messages immediately upon instancing the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing under those conditions<br />**Default:** true | `Boolean` |
 | echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Default:** true | `Boolean` |
 | autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Default:** true | `Boolean` |
-| queryTime | 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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Default:** 15,000ms | `Integer` |
 | suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Default:** 30,000ms | `Integer` |
@@ -2124,17 +2124,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Property | Description | Type |
 |----------|-------------|------|
-| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| Token | An authenticated [`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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| AuthCallback | A function 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 | `Callable` |
+| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| Token | An authenticated [`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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| AuthCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls | `Callable` |
 | AuthUrl | 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 | `String` |
 | AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />**Default:** `GET` | `String` |
 | AuthHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response | `Map<String, String>` |
 | AuthParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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 | `Map<String, String>` |
-| TokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| TokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | Tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />**Default:** true | `Boolean` |
-| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
+| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| UseTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)<br />**Default:** false | `Boolean` |
 | Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details<br />**Default:** null | `String` |
 | IdempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default<br />**Default:** false | `Boolean` |
@@ -2144,7 +2144,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | QueueMessages | If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior allows applications to submit messages immediately upon instancing the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing under those conditions<br />**Default:** true | `Boolean` |
 | EchoMessages | If false, prevents messages originating from this connection being echoed back on the same connection<br />**Default:** true | `Boolean` |
 | AutoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method<br />**Default:** true | `Boolean` |
-| QueryTime | 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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
+| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/realtime-sdk/authentication#request-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<br />**Default:** false | `Boolean` |
 | DefaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) |
 | DisconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically<br />**Default:** 15,000ms | `Integer` |
 | SuspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically<br />**Default:** 30,000ms | `Integer` |
@@ -3283,25 +3283,25 @@ Mark the `Deferrable` as succeeded and trigger all callbacks. See the [EventMach
 
 <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:
+`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/platform/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="java,csharp">
 
-`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).
+`TokenParams` is used in the parameters of [token authentication](/docs/platform/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).
+`ARTTokenParams` is used in the parameters of [token authentication](/docs/platform/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details).
 
 </If>
 
@@ -3309,8 +3309,8 @@ Mark the `Deferrable` as succeeded and trigger all callbacks. See the [EventMach
 
 | Property | Description | Type |
 |----------|-------------|------|
-| <If lang="javascript,nodejs,java,objc,swift,flutter">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,swift,ruby,flutter,go">`String`</If><If lang="csharp">`Capability`</If> |
-| <If lang="javascript,nodejs,java,objc,swift,flutter">clientId</If><If lang="csharp,go">ClientId</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,swift,flutter">`clientId`</If><If lang="ruby">`: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,swift,flutter">`clientId`</If><If lang="ruby">`: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,swift,flutter">`clientId`</If><If lang="ruby">`:client_id`</If><If lang="csharp,go">`ClientId`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,swift,flutter">`clientId`</If><If lang="ruby">`: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,swift,flutter">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/platform/auth/capabilities). | <If lang="javascript,nodejs,java,objc,swift,ruby,flutter,go">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,java,objc,swift,flutter">clientId</If><If lang="csharp,go">ClientId</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,swift,flutter">`clientId`</If><If lang="ruby">`: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,swift,flutter">`clientId`</If><If lang="ruby">`: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,swift,flutter">`clientId`</If><If lang="ruby">`:client_id`</If><If lang="csharp,go">`ClientId`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,swift,flutter">`clientId`</If><If lang="ruby">`:client_id`</If><If lang="csharp,go">`ClientId`</If> implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
 | <If lang="javascript,nodejs,java,objc,swift,flutter">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,swift,flutter">timestamp</If><If lang="csharp,go">Timestamp</If><If lang="ruby">:timestamp</If> | <If lang="javascript,nodejs,java,flutter">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,flutter">`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,swift,flutter">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,flutter">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,flutter">`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> |
diff --git a/src/pages/docs/api/rest-api.mdx b/src/pages/docs/api/rest-api.mdx
index 269187edbd..203d593344 100644
--- a/src/pages/docs/api/rest-api.mdx
+++ b/src/pages/docs/api/rest-api.mdx
@@ -295,7 +295,7 @@ Envelope responses always are always made with a 200 status code; the status of
 
 ## Authentication <a id="authentication" />
 
-To understand the REST API it is easiest first to understand the various authentication methods that Ably supports. For a detailed explanation, view the [Authentication documentation](/docs/auth).
+To understand the REST API it is easiest first to understand the various authentication methods that Ably supports. For a detailed explanation, view the [Authentication documentation](/docs/platform/auth).
 
 Clients can access Ably, whether using REST or the Realtime service, by two methods:
 
@@ -343,7 +343,7 @@ curl https://main.realtime.ably.net/channels/rest-example/messages \
 
 ### Token Authentication <a id="token-authentication" />
 
-**Token Authentication** uses an Ably-compatible token to authenticate with Ably without sharing a private API key. This can be an [Ably Token](/docs/api/rest-sdk/authentication#tokens) obtained via the REST API [`requestToken`](#request-token) endpoint, an [Ably JWT](/docs/api/rest-sdk/authentication#ably-jwt) signed by your API key, or an [External JWT](https://jwt.io) object [with an embedded Ably-compatible token](/docs/auth/token#embedded). Tokens are authentication credentials that are short-lived, and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope - such as a limited set of [access rights or capabilities](/docs/auth/capabilities) or being limited to use by a specific [`clientId` identity](#identified-clients) - and therefore token-based authentication provides the flexibility to implement access and identity control policies in the application. See the [Token Authentication documentation](/docs/auth/token) for more details.
+**Token Authentication** uses an Ably-compatible token to authenticate with Ably without sharing a private API key. This can be an [Ably Token](/docs/api/rest-sdk/authentication#tokens) obtained via the REST API [`requestToken`](#request-token) endpoint, an [Ably JWT](/docs/api/rest-sdk/authentication#ably-jwt) signed by your API key, or an [External JWT](https://jwt.io) object [with an embedded Ably-compatible token](/docs/platform/auth/token#embedded). Tokens are authentication credentials that are short-lived, and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope - such as a limited set of [access rights or capabilities](/docs/platform/auth/capabilities) or being limited to use by a specific [`clientId` identity](#identified-clients) - and therefore token-based authentication provides the flexibility to implement access and identity control policies in the application. See the [Token Authentication documentation](/docs/platform/auth/token) for more details.
 
 The construction of an Ably [`TokenRequest`](/docs/api/token-request-spec) is described in the [Authentication Ably TokenRequest spec documentation](/docs/api/token-request-spec). The resulting `token response` object contains the token properties as defined in [Ably TokenRequest spec](/docs/api/token-request-spec).
 
@@ -1681,7 +1681,7 @@ A successful request returns a [paginated response](#pagination) of:
 
 ### Publish directly to specific recipients <a id="push-publish" />
 
-Convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their [client identifier](/docs/auth/identified-clients).
+Convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their [client identifier](/docs/platform/auth/identified-clients).
 
 If you want to send a push notification to subscribed clients without knowing about recipient devices' details, we recommend you look at [registering devices for push](#post-device-registration), then [subscribe them to channels](#post-channel-subscription), and then [send messages to the channels with push payloads](#message-extras-push).
 
@@ -1943,7 +1943,7 @@ The request body has the following properties:
 
 | Property | Description |
 |----------|-------------|
-| targets | An array of [target specifier](/docs/auth/revocation#target-specifiers) strings. |
+| targets | An array of [target specifier](/docs/platform/auth/revocation#target-specifiers) strings. |
 | issuedBefore | Optional number (Unix timestamp in milliseconds); if not specified it is set to the current time. The token revocation only applies to tokens issued before this timestamp. A request with an `issuedBefore` in the future, or more than an hour in the past will be rejected. |
 | allowReauthMargin | The `allowReauthMargin` bool 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. It defaults to `false`, meaning that the effect is near-immediate. |
 
@@ -1974,7 +1974,7 @@ The response is comparable to that of [Batch publish](#batch). If some tokens ca
 
 ##### See also
 
-See the [token revocation documentation](/docs/auth/revocation) for further details.
+See the [token revocation documentation](/docs/platform/auth/revocation) for further details.
 
 ## Application routes <a id="application" />
 
@@ -2027,7 +2027,7 @@ Stats records contain a hierarchy of elements relating to messages, connections
 
 Ably's message statistics categorize unsuccessful message delivery into two distinct types: refused and failed messages.
 
-**Refused messages** are actively rejected by Ably's system. The most common cause is breaching a [rate limit](/docs/platform/pricing/limits), though refusals can also occur due to malformed message structure, insufficient [channel permissions](/docs/auth/capabilities), or other request defects.
+**Refused messages** are actively rejected by Ably's system. The most common cause is breaching a [rate limit](/docs/platform/pricing/limits), though refusals can also occur due to malformed message structure, insufficient [channel permissions](/docs/platform/auth/capabilities), or other request defects.
 
 **Failed messages** represent delivery attempts that were unsuccessful for reasons other than active rejection by Ably. This category includes internal service issues and rejections from external systems. In the case of [Integrations](/docs/platform/integrations) or [Push Notifications](/docs/push), when an external target rejects a message, it appears in statistics as a failed message.
 
diff --git a/src/pages/docs/api/rest-sdk.mdx b/src/pages/docs/api/rest-sdk.mdx
index 0967d0235c..fafc69fafc 100644
--- a/src/pages/docs/api/rest-sdk.mdx
+++ b/src/pages/docs/api/rest-sdk.mdx
@@ -10,7 +10,7 @@ redirect_from:
 
 ## Constructor <a id="constructor" />
 
-The Ably REST library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/auth/basic) or [Token](/docs/auth/token).
+The Ably REST library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/platform/auth/basic) or [Token](/docs/platform/auth/token).
 
 <If lang="javascript,nodejs">
 
@@ -153,11 +153,11 @@ The REST constructor is used to instantiate the library. The REST library may be
 
 ### Authentication <a id="authentication" />
 
-The REST library needs to have credentials to be able to authenticate with the Ably service. Ably supports both Basic and Token based authentication schemes. Read more on [authentication](/docs/auth).
+The REST library needs to have credentials to be able to authenticate with the Ably service. Ably supports both Basic and Token based authentication schemes. Read more on [authentication](/docs/platform/auth).
 
 #### Basic Authentication
 
-A private API key string for <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift">[`ClientOptions#key`](#client-options)</If><If lang="csharp,go">[`ClientOptions#Key`](#client-options)</If> or the constructor, as obtained from the [application dashboard](https://ably.com/dashboard), is required for [Basic Authentication](/docs/auth/basic). Use this option if you wish to use [Basic authentication](/docs/auth/basic), or if you want to be able to [request Ably Tokens](/docs/auth/token) without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift">`key`</If><If lang="csharp,go">`Key`</If> does not necessarily mean that the library will use Basic auth; using the private key it is also able to create and sign Ably TokenRequests and use token authentication when necessary.
+A private API key string for <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift">[`ClientOptions#key`](#client-options)</If><If lang="csharp,go">[`ClientOptions#Key`](#client-options)</If> or the constructor, as obtained from the [application dashboard](https://ably.com/dashboard), is required for [Basic Authentication](/docs/platform/auth/basic). Use this option if you wish to use [Basic authentication](/docs/platform/auth/basic), or if you want to be able to [request Ably Tokens](/docs/platform/auth/token) without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift">`key`</If><If lang="csharp,go">`Key`</If> does not necessarily mean that the library will use Basic auth; using the private key it is also able to create and sign Ably TokenRequests and use token authentication when necessary.
 
 #### Token Authentication
 
@@ -165,7 +165,7 @@ The <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift">[`Clien
 
 Since tokens are short-lived, it is rarely sufficient to start with a token without the means for refreshing it. The <If lang="javascript,nodejs,flutter,java,objc,swift">[`authUrl` and `authCallback` options](#client-options)</If><If lang="ruby">[`:auth_url` and `:auth_callback` options](#client-options)</If><If lang="python">[`auth_url` and `auth_callback` options](#client-options)</If><If lang="csharp,go">[`AuthUrl` and `AuthCallback` options](#client-options)</If> are provided to allow a user of the library to provide new Ably-compatible tokens or Ably TokenRequests to the library as required; using these options allows the library to be instantiated without a <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift">`key` or `token`</If><If lang="csharp,go">`Key` or `Token`</If>, and an initial token will be obtained automatically when required.
 
-Read more on [authentication](/docs/auth).
+Read more on [authentication](/docs/platform/auth).
 
 <If lang="objc,swift">
 
@@ -686,17 +686,17 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| <If lang="javascript,nodejs,java,objc,php,python,swift">key</If><If lang="go">Key</If><If lang="ruby">:key</If> | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| <If lang="javascript,nodejs,java,objc,php,python,swift">token</If><If lang="go">Token</If><If lang="ruby">: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,python,swift">`token`</If><If lang="go">`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="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">`authCallback`</If><If lang="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,java,objc,php,swift">authCallback</If><If lang="go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,flutter,java,objc,php,python,swift,go,ruby">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> 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,python,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">key</If><If lang="go">Key</If><If lang="ruby">:key</If> | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">token</If><If lang="go">Token</If><If lang="ruby">: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,python,swift">`token`</If><If lang="go">`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/platform/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="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">`authCallback`</If><If lang="go">`AuthCallback`</If><If lang="python">`auth_callback`</If><If lang="ruby">`:auth_callback`</If>. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| <If lang="javascript,nodejs,java,objc,php,swift">authCallback</If><If lang="go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,flutter,java,objc,php,python,swift,go,ruby">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> 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | <If lang="javascript,nodejs,java,objc,php,python,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authUrl</If><If lang="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,flutter,java,objc,php,python,ruby,go">`String`</If><If lang="swift,objc">`NSURL`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authMethod</If><If lang="go">AuthMethod</If><If lang="python">auth_method</If><If lang="ruby">:auth_method</If> | The HTTP verb to use for the request, either <If lang="javascript,nodejs,java,objc,php,python,swift,go">`GET`</If><If lang="ruby">`:get`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift,go">`POST`</If><If lang="ruby">`:post`</If><br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">`GET`</If><If lang="ruby">`:get`</If>_ | <If lang="javascript,nodejs,java,objc,php,python,swift,go">`String`</If><If lang="ruby">`Symbol`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authHeaders</If><If lang="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,flutter,java,objc,php,python,ruby,swift,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,java,objc,php,python,swift,go">`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="flutter">`Map<String, String>`</If> |
 | <If lang="javascript,nodejs,java,objc,php,,swift">authParams</If><If lang="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,flutter,java,objc,php,python,ruby,swift,go">`authUrl`</If>. When the <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift,go">`authMethod`</If><If lang="go">`AuthMethod`</If> is `GET`, query params are added to the URL, whereas when <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift,go">`authMethod`</If><If lang="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,java,objc,php,python,swift,go">`Object`</If><If lang="ruby">`Hash`</If><If lang="php">`Associative Array`</If><If lang="java">`Param[]`</If><If lang="objc">`NSArray<NSURLQueryItem *>`</If><If lang="swift">`[NSURLQueryItem]/Array<NSURLQueryItem>`</If><If lang="flutter">`Map<String, String>`</If> |
-| <If lang="javascript,nodejs,java,objc,php,swift">tokenDetails</If><If lang="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,python,swift">`authUrl`</If><If lang="go">`AuthUrl`</If><If lang="ruby">`:auth_url`</If><If lang="python">`auth_url`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift">`authCallback`</If><If lang="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">tokenDetails</If><If lang="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,python,swift">`authUrl`</If><If lang="go">`AuthUrl`</If><If lang="ruby">`:auth_url`</If><If lang="python">`auth_url`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift">`authCallback`</If><If lang="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/platform/auth/token) | `TokenDetails` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">tls</If><If lang="go">Tls</If><If lang="ruby">:tls</If> | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />_default: true_ | `Boolean` |
-| <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,php,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,swift">useTokenAuth</If><If lang="go">UseTokenAuth</If><If lang="python">use_token_auth</If><If lang="ruby">:use_token_auth</If> | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a <If lang="ruby,python">`client_id`</If><If lang="javascript,nodejs,java,objc,php,python,swift,go">`clientId`</If> is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
+| <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,php,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="go">`ClientId`</If> implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,swift">useTokenAuth</If><If lang="go">UseTokenAuth</If><If lang="python">use_token_auth</If><If lang="ruby">:use_token_auth</If> | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a <If lang="ruby,python">`client_id`</If><If lang="javascript,nodejs,java,objc,php,python,swift,go">`clientId`</If> is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">endpoint</If><If lang="go">Endpoint</If><If lang="ruby">:endpoint</If> | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">null</If><If lang="java">Null</If><If lang="python">None</If><If lang="ruby,objc,swift">nil</If>_ | `String` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">environment</If><If lang="go">Environment</If><If lang="ruby">:environment</If> | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">null</If><If lang="java">Null</If><If lang="python">None</If><If lang="ruby,objc,swift">nil</If>_ | `String` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">idempotentRestPublishing</If><If lang="go">IdempotentRestPublishing</If><If lang="ruby">:idempotent_rest_publishing</If> | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.<br />_default: false_ | `Boolean` |
@@ -706,7 +706,7 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 | <If lang="javascript,nodejs,java,objc,php,swift">logHandler</If><If lang="python">log_handler</If> | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` |
 | transports | An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: `web_socket`, `xhr_polling`. | `String[]` |
 | <If lang="javascript,nodejs,java,objc,php,swift">useBinaryProtocol</If><If lang="python">use_binary_protocol</If> | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />_default: false_ | `Boolean` |
-| <If lang="javascript,nodejs,java,objc,php,swift">queryTime</If><If lang="go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | 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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
+| <If lang="javascript,nodejs,java,objc,php,swift">queryTime</If><If lang="go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
 | <If lang="javascript,nodejs,java,objc,php,swift">defaultTokenParams</If><If lang="python">default_token_params</If><If lang="ruby">:default_token_params</If><If lang="go">DefaultTokenParams</If> | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -716,17 +716,17 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| Token | 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 `Token` 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| AuthCallback | A function 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. | `Callable` |
+| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| Token | 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 `Token` 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/platform/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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| AuthCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | AuthUrl | 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. | `String` |
 | AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />_default: `GET`_ | `String` |
 | AuthHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Object` |
 | AuthParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `AuthMethod` is `GET`, query params are added to the URL, whereas when `AuthMethod` 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. | `Object` |
-| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | Tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />_default: true_ | `Boolean` |
-| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `ClientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
+| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| UseTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `ClientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
 | Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: null_ | `String` |
 | Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: null_ | `String` |
 | IdempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.<br />_default: false_ | `Boolean` |
@@ -734,7 +734,7 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 | transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object` |
 | LogLevel | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` |
 | UseBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />_default: false_ | `Boolean` |
-| QueryTime | 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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
+| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
 | DefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -745,17 +745,17 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| :token | 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 `token` 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 `:auth_url` or `:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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. | `Proc` |
+| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| :token | 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 `token` 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/platform/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 `:auth_url` or `:auth_callback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Proc` |
 | :auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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. | `String` |
 | :auth_method | The HTTP verb to use for the request, either `:get` or `:post`<br />_default: `:get`_ | `Symbol` |
 | :auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Hash` |
 | :auth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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. | `Hash` |
-| :token_details | 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 `:auth_url` or `:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| :token_details | 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 `:auth_url` or `:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | :tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />_default: true_ | `Boolean` |
-| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| :use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
+| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| :use_token_auth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
 | :endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: nil_ | `String` |
 | :environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: nil_ | `String` |
 | :idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.<br />_default: false_ | `Boolean` |
@@ -764,7 +764,7 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 | :log_level | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` |
 | :logger | A Ruby [`Logger`](http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html) compatible object to handle each line of log output. If `logger` is not specified, `STDOUT` is used. | `STDOUT Logger` |
 | :use_binary_protocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />_default: true_ | `Boolean` |
-| :query_time | 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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
+| :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
 | :default_token_params | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 
@@ -775,24 +775,24 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| <If lang="javascript,nodejs,java,objc,php,python,swift">key</If><If lang="go">Key</If><If lang="ruby">:key</If> | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| <If lang="javascript,nodejs,java,objc,php,python,swift">token</If><If lang="go">Token</If><If lang="ruby">: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,python,swift">`token`</If><If lang="go">`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="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">`authCallback`</If><If lang="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,java,objc,php,swift">authCallback</If><If lang="go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,flutter,java,objc,php,python,swift,go,ruby">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> 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,python,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">key</If><If lang="go">Key</If><If lang="ruby">:key</If> | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">token</If><If lang="go">Token</If><If lang="ruby">: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,python,swift">`token`</If><If lang="go">`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/platform/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="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">`authCallback`</If><If lang="go">`AuthCallback`</If><If lang="python">`auth_callback`</If><If lang="ruby">`:auth_callback`</If>. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| <If lang="javascript,nodejs,java,objc,php,swift">authCallback</If><If lang="go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,flutter,java,objc,php,python,swift,go,ruby">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> 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | <If lang="javascript,nodejs,java,objc,php,python,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authUrl</If><If lang="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,flutter,java,objc,php,python,ruby,go">`String`</If><If lang="swift,objc">`NSURL`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authMethod</If><If lang="go">AuthMethod</If><If lang="python">auth_method</If><If lang="ruby">:auth_method</If> | The HTTP verb to use for the request, either <If lang="javascript,nodejs,java,objc,php,python,swift,go">`GET`</If><If lang="ruby">`:get`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift,go">`POST`</If><If lang="ruby">`:post`</If><br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">`GET`</If><If lang="ruby">`:get`</If>_ | <If lang="javascript,nodejs,java,objc,php,python,swift,go">`String`</If><If lang="ruby">`Symbol`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authHeaders</If><If lang="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,flutter,java,objc,php,python,ruby,swift,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,java,objc,php,python,swift,go">`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="flutter">`Map<String, String>`</If> |
 | <If lang="javascript,nodejs,java,objc,php,,swift">authParams</If><If lang="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,flutter,java,objc,php,python,ruby,swift,go">`authUrl`</If>. When the <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift,go">`authMethod`</If><If lang="go">`AuthMethod`</If> is `GET`, query params are added to the URL, whereas when <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift,go">`authMethod`</If><If lang="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,java,objc,php,python,swift,go">`Object`</If><If lang="ruby">`Hash`</If><If lang="php">`Associative Array`</If><If lang="java">`Param[]`</If><If lang="objc">`NSArray<NSURLQueryItem *>`</If><If lang="swift">`[NSURLQueryItem]/Array<NSURLQueryItem>`</If><If lang="flutter">`Map<String, String>`</If> |
-| <If lang="javascript,nodejs,java,objc,php,swift">tokenDetails</If><If lang="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,python,swift">`authUrl`</If><If lang="go">`AuthUrl`</If><If lang="ruby">`:auth_url`</If><If lang="python">`auth_url`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift">`authCallback`</If><If lang="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">tokenDetails</If><If lang="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,python,swift">`authUrl`</If><If lang="go">`AuthUrl`</If><If lang="ruby">`:auth_url`</If><If lang="python">`auth_url`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift">`authCallback`</If><If lang="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/platform/auth/token) | `TokenDetails` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">tls</If><If lang="go">Tls</If><If lang="ruby">:tls</If> | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />_default: true_ | `Boolean` |
-| <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,php,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,swift">useTokenAuth</If><If lang="go">UseTokenAuth</If><If lang="python">use_token_auth</If><If lang="ruby">:use_token_auth</If> | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a <If lang="ruby,python">`client_id`</If><If lang="javascript,nodejs,java,objc,php,python,swift,go">`clientId`</If> is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
+| <If lang="javascript,nodejs,java,objc,php,swift">clientId</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,php,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="go">`ClientId`</If> implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,swift">useTokenAuth</If><If lang="go">UseTokenAuth</If><If lang="python">use_token_auth</If><If lang="ruby">:use_token_auth</If> | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a <If lang="ruby,python">`client_id`</If><If lang="javascript,nodejs,java,objc,php,python,swift,go">`clientId`</If> is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">endpoint</If><If lang="go">Endpoint</If><If lang="ruby">:endpoint</If> | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">null</If><If lang="java">Null</If><If lang="python">None</If><If lang="ruby,objc,swift">nil</If>_ | `String` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">environment</If><If lang="go">Environment</If><If lang="ruby">:environment</If> | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">null</If><If lang="java">Null</If><If lang="python">None</If><If lang="ruby,objc,swift">nil</If>_ | `String` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">idempotentRestPublishing</If><If lang="go">IdempotentRestPublishing</If><If lang="ruby">:idempotent_rest_publishing</If> | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.<br />_default: false_ | `Boolean` |
 | <If lang="javascript,nodejs,java,objc,php,swift">fallbackHosts</If><If lang="go">FallbackHosts</If><If lang="python">fallback_hosts</If><If lang="ruby">:fallback_hosts</If> | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.<br />_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` |
 | <If lang="javascript,nodejs,java,objc,php,swift">transportParams</If><If lang="python">transport_params</If><If lang="ruby">:transport_params</If> | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | <If lang="javascript,nodejs,java,objc,php,swift,go">`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="flutter">`Map<String, String>`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">useBinaryProtocol</If><If lang="python">use_binary_protocol</If> | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />_default: false_ | `Boolean` |
-| <If lang="javascript,nodejs,java,objc,php,swift">queryTime</If><If lang="go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | 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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
+| <If lang="javascript,nodejs,java,objc,php,swift">queryTime</If><If lang="go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
 | <If lang="javascript,nodejs,java,objc,php,swift">defaultTokenParams</If><If lang="python">default_token_params</If><If lang="ruby">:default_token_params</If><If lang="go">DefaultTokenParams</If> | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -802,17 +802,17 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| <If lang="javascript,nodejs,java,objc,php,python,swift">key</If><If lang="go">Key</If><If lang="ruby">:key</If> | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| <If lang="javascript,nodejs,java,objc,php,python,swift">token</If><If lang="go">Token</If><If lang="ruby">: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,python,swift">`token`</If><If lang="go">`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="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">`authCallback`</If><If lang="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,java,objc,php,swift">authCallback</If><If lang="go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,flutter,java,objc,php,python,swift,go,ruby">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> 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,python,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If> |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">key</If><If lang="go">Key</If><If lang="ruby">:key</If> | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">token</If><If lang="go">Token</If><If lang="ruby">: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,python,swift">`token`</If><If lang="go">`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/platform/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="ruby">:auth_url</If><If lang="python">auth_url</If> or <If lang="javascript,nodejs,java,objc,php,swift">`authCallback`</If><If lang="go">`AuthCallback`</If><If lang="python">`auth_callback`</If><If lang="ruby">`:auth_callback`</If>. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| <If lang="javascript,nodejs,java,objc,php,swift">authCallback</If><If lang="go">AuthCallback</If><If lang="python">auth_callback</If><If lang="ruby">:auth_callback</If> | A <If lang="javascript,nodejs,flutter,java,objc,php,python,swift,go,ruby">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> 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | <If lang="javascript,nodejs,java,objc,php,python,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authUrl</If><If lang="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,flutter,java,objc,php,python,ruby,go">`String`</If><If lang="swift,objc">`NSURL`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authMethod</If><If lang="go">AuthMethod</If><If lang="python">auth_method</If><If lang="ruby">:auth_method</If> | The HTTP verb to use for the request, either <If lang="javascript,nodejs,java,objc,php,python,swift,go">`GET`</If><If lang="ruby">`:get`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift,go">`POST`</If><If lang="ruby">`:post`</If><br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">`GET`</If><If lang="ruby">`:get`</If>_ | <If lang="javascript,nodejs,java,objc,php,python,swift,go">`String`</If><If lang="ruby">`Symbol`</If> |
 | <If lang="javascript,nodejs,java,objc,php,swift">authHeaders</If><If lang="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,flutter,java,objc,php,python,ruby,swift,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,java,objc,php,python,swift,go">`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="flutter">`Map<String, String>`</If> |
 | <If lang="javascript,nodejs,java,objc,php,,swift">authParams</If><If lang="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,flutter,java,objc,php,python,ruby,swift,go">`authUrl`</If>. When the <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift,go">`authMethod`</If><If lang="go">`AuthMethod`</If> is `GET`, query params are added to the URL, whereas when <If lang="javascript,nodejs,flutter,java,objc,php,python,ruby,swift,go">`authMethod`</If><If lang="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,java,objc,php,python,swift,go">`Object`</If><If lang="ruby">`Hash`</If><If lang="php">`Associative Array`</If><If lang="java">`Param[]`</If><If lang="objc">`NSArray<NSURLQueryItem *>`</If><If lang="swift">`[NSURLQueryItem]/Array<NSURLQueryItem>`</If><If lang="flutter">`Map<String, String>`</If> |
-| <If lang="javascript,nodejs,java,objc,php,python,swift">tokenDetails</If><If lang="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,python,swift">`authUrl`</If><If lang="go">`AuthUrl`</If><If lang="ruby">`:auth_url`</If><If lang="python">`auth_url`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift">`authCallback`</If><If lang="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,python,swift">tokenDetails</If><If lang="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,python,swift">`authUrl`</If><If lang="go">`AuthUrl`</If><If lang="ruby">`:auth_url`</If><If lang="python">`auth_url`</If> or <If lang="javascript,nodejs,java,objc,php,python,swift">`authCallback`</If><If lang="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/platform/auth/token) | `TokenDetails` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">tls</If><If lang="go">Tls</If><If lang="ruby">:tls</If> | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />_default: true_ | `Boolean` |
-| <If lang="javascript,nodejs,java,objc,php,python,swift">clientId</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,php,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,swift">useTokenAuth</If><If lang="go">UseTokenAuth</If><If lang="python">use_token_auth</If><If lang="ruby">:use_token_auth</If> | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a <If lang="ruby,python">`client_id`</If><If lang="javascript,nodejs,java,objc,php,python,swift,go">`clientId`</If> is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">clientId</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="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,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If> specified here conflicts with the <If lang="javascript,nodejs,java,objc,php,python,swift">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="go">`ClientId`</If> implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">useTokenAuth</If><If lang="go">UseTokenAuth</If><If lang="python">use_token_auth</If><If lang="ruby">:use_token_auth</If> | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a <If lang="ruby,python">`client_id`</If><If lang="javascript,nodejs,java,objc,php,python,swift,go">`clientId`</If> is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">endpoint</If><If lang="go">Endpoint</If><If lang="ruby">:endpoint</If> | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">null</If><If lang="java">Null</If><If lang="python">None</If><If lang="ruby,objc,swift">nil</If>_ | `String` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">environment</If><If lang="go">Environment</If><If lang="ruby">:environment</If> | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: <If lang="javascript,nodejs,java,objc,php,python,swift,go">null</If><If lang="java">Null</If><If lang="python">None</If><If lang="ruby,objc,swift">nil</If>_ | `String` |
 | <If lang="javascript,nodejs,java,objc,php,python,swift">idempotentRestPublishing</If><If lang="go">IdempotentRestPublishing</If><If lang="ruby">:idempotent_rest_publishing</If> | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.<br />_default: false_ | `Boolean` |
@@ -821,7 +821,7 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 | <If lang="javascript,nodejs,java,objc,php,swift">logLevel</If><If lang="python">log_level</If> | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` |
 | <If lang="javascript,nodejs,java,objc,php,swift">logHandler</If><If lang="python">log_handler</If> | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` |
 | <If lang="javascript,nodejs,java,objc,php,swift">useBinaryProtocol</If><If lang="python">use_binary_protocol</If> | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />_default: false_ | `Boolean` |
-| <If lang="javascript,nodejs,java,objc,php,python,swift">queryTime</If><If lang="go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | 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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
+| <If lang="javascript,nodejs,java,objc,php,python,swift">queryTime</If><If lang="go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
 | <If lang="javascript,nodejs,java,objc,php,swift">defaultTokenParams</If><If lang="python">default_token_params</If><If lang="ruby">:default_token_params</If><If lang="go">DefaultTokenParams</If> | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -831,24 +831,24 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | 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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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. | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | 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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | authUrl | 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. | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />_default: `GET`_ | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Map<String, String>` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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. | `Map<String, String>` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />_default: true_ | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: null_ | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: null_ | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.<br />_default: false_ | `Boolean` |
 | fallbackHosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.<br />_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` |
 | transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Map<String, String>` |
 | useBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />_default: false_ | `Boolean` |
-| queryTime | 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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
 | defaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -860,17 +860,17 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| Token | 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 `Token` 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| AuthCallback | A function 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. | `Func<TokenParams, Task<object>>` |
+| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| Token | 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 `Token` 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/platform/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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| AuthCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Func<TokenParams, Task<object>>` |
 | AuthUrl | 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. | `Uri` |
 | AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`<br />_default: `GET`_ | `HttpMethod` |
 | AuthHeaders | A set of key value pair headers to be added to any request made to the `AuthUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Dictionary<string, string>` |
 | AuthParams | A set of key value pair params to be added to any request made to the `AuthUrl`. When the `AuthMethod` is `GET`, query params are added to the URL, whereas when `AuthMethod` 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. | `Dictionary<string, string>` |
-| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | Tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)<br />_default: true_ | `Boolean` |
-| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
+| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| UseTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).<br />_default: false_ | `Boolean` |
 | Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: null_ | `String` |
 | Environment | Deprecated, use `Endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.<br />_default: null_ | `String` |
 | IdempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.<br />_default: false_ | `Boolean` |
@@ -879,7 +879,7 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#
 | LogLevel | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` |
 | LoggerSink | The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure.<br />_default: IO.Ably.DefaultLoggerSink_ | `ILoggerSink` |
 | UseBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)<br />_default: false_ | `Boolean` |
-| QueryTime | 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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
+| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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.<br />_default: false_ | `Boolean` |
 | DefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
diff --git a/src/pages/docs/api/rest-sdk/authentication.mdx b/src/pages/docs/api/rest-sdk/authentication.mdx
index 97023b4331..2c208b3a1a 100644
--- a/src/pages/docs/api/rest-sdk/authentication.mdx
+++ b/src/pages/docs/api/rest-sdk/authentication.mdx
@@ -29,7 +29,7 @@ In the documentation, references to Ably-compatible tokens typically refer eithe
 
 ## 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.
+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/platform/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>.
 
@@ -339,11 +339,11 @@ fmt.Println(token)
 
 </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.
+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/platform/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).
+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/platform/auth/token).
 
 #### Parameters
 
@@ -582,7 +582,7 @@ Calls the <If lang="javascript,nodejs,php,java,ruby,python,objc,swift">[`request
 
 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).
+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/platform/auth/token).
 
 #### Parameters
 
@@ -800,7 +800,7 @@ fmt.Println(token)
 
 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.
+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/platform/auth/revocation) for more information.
 
 #### Parameters
 
@@ -854,42 +854,42 @@ try {
 ### <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:
+`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is a Hash object and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is a Dict and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is an Associative Array and is used when making [authentication](/docs/platform/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.
+`AuthOptions` is used when making [authentication](/docs/platform/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.
+`ARTAuthOptions` is used when making [authentication](/docs/platform/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">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/platform/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,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/platform/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/platform/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/platform/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/platform/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/platform/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/platform/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" />
 
@@ -902,8 +902,8 @@ try {
 | <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="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/platform/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/platform/auth/identified-clients) | `String` |
 
 <If lang="ruby">
 ### Methods
@@ -959,35 +959,35 @@ 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:
+`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is a Dict and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is an Associative Array and is used in the parameters of [token authentication](/docs/platform/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).
+`TokenParams` is used in the parameters of [token authentication](/docs/platform/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).
+`ARTTokenParams` is used in the parameters of [token authentication](/docs/platform/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,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/platform/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/platform/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> |
@@ -1003,7 +1003,7 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object
 | <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,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/platform/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` |
@@ -1047,7 +1047,7 @@ An Ably JWT is not strictly an Ably construct, rather it is a [JWT](https://jwt.
 
 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.
+The Ably JWT must be signed with the secret part of your [Ably API key](/docs/platform/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.
 
diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx
index 022178675c..c7b498af0d 100644
--- a/src/pages/docs/api/rest-sdk/channels.mdx
+++ b/src/pages/docs/api/rest-sdk/channels.mdx
@@ -471,7 +471,7 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e
 
 `getMessage(serialOrMessage: string | Message): Promise<Message>`
 
-Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities).
+Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/platform/auth/capabilities).
 
 See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information.
 
@@ -551,7 +551,7 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR
 
 `getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`
 
-Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities).
+Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/platform/auth/capabilities).
 
 See [updating and deleting messages: versions](/docs/messages/updates-deletes#versions) for more information.
 
diff --git a/src/pages/docs/api/rest-sdk/push-admin.mdx b/src/pages/docs/api/rest-sdk/push-admin.mdx
index 097fb57e21..116dfa392f 100644
--- a/src/pages/docs/api/rest-sdk/push-admin.mdx
+++ b/src/pages/docs/api/rest-sdk/push-admin.mdx
@@ -29,7 +29,7 @@ The returned [`DeviceRegistrations`](#device-registrations-object) object provid
 
 #### <If lang="javascript,nodejs,java,android,php,swift,objc">channelSubscriptions</If><If lang="ruby">channel_subscriptions</If> <a id="channel-subscriptions" />
 
-The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object provides functionality for subscribing, listing and unsubscribing individual devices or groups of [identified devices](/docs/auth/identified-clients) to push notifications published on channels.
+The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object provides functionality for subscribing, listing and unsubscribing individual devices or groups of [identified devices](/docs/platform/auth/identified-clients) to push notifications published on channels.
 
 ### Methods <a id="methods" />
 
@@ -65,7 +65,7 @@ The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object pr
 
 </If>
 
-Publishes a push notification directly to a device or group of devices sharing a [client identifier](/docs/auth/identified-clients). See the [push notification direct publishing documentation](/docs/push/publish#direct-publishing) for more information.
+Publishes a push notification directly to a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients). See the [push notification direct publishing documentation](/docs/push/publish#direct-publishing) for more information.
 
 ##### Parameters
 
@@ -692,7 +692,7 @@ This object is accessible through <If lang="javascript,nodejs,java,android,php,s
 
 </If>
 
-Retrieve all push channel subscriptions that match the provided params filter as a paginated list of [`PushChannelSubscription`](#push-channel-subscription) objects. Each [`PushChannelSubscription`](#push-channel-subscription) represents a device or set of devices sharing the same [client identifier](/docs/auth/identified-clients) registered to a channel to receive push notifications.
+Retrieve all push channel subscriptions that match the provided params filter as a paginated list of [`PushChannelSubscription`](#push-channel-subscription) objects. Each [`PushChannelSubscription`](#push-channel-subscription) represents a device or set of devices sharing the same [client identifier](/docs/platform/auth/identified-clients) registered to a channel to receive push notifications.
 
 ##### Parameters
 
@@ -876,7 +876,7 @@ Failure to retrieve the channels will trigger the `errback` callbacks of the [`D
 
 </If>
 
-Subscribe a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) for push notifications published on a channel.
+Subscribe a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) for push notifications published on a channel.
 
 ##### Parameters
 
@@ -934,7 +934,7 @@ On failure to create or update the channel subscription, `err` contains an [`Err
 
 </If>
 
-Unsubscribe a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) from push notifications on a channel. Requires `push-admin` permission or, in the case of a subscription associated with a given `deviceId`, `push-subscribe` permission together with device authentication matching that `deviceId`.
+Unsubscribe a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) from push notifications on a channel. Requires `push-admin` permission or, in the case of a subscription associated with a given `deviceId`, `push-subscribe` permission together with device authentication matching that `deviceId`.
 
 ##### Parameters
 
@@ -1037,7 +1037,7 @@ A `DeviceDetails` is a type encapsulating attributes of a device registered for
 | Property | Description | Type |
 |----------|-------------|------|
 | id | unique identifier for the device generated by the device itself | String |
-| <If lang="javascript,nodejs,java,android,php,swift,objc">clientId</If><If lang="ruby">client_id</If> | optional trusted [client identifier](/docs/auth/identified-clients) for the device | String |
+| <If lang="javascript,nodejs,java,android,php,swift,objc">clientId</If><If lang="ruby">client_id</If> | optional trusted [client identifier](/docs/platform/auth/identified-clients) for the device | String |
 | <If lang="javascript,nodejs,java,android,php,swift,objc">formFactor</If><If lang="ruby">form_factor</If> | form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` <If lang="javascript,nodejs,java,android,php,ruby,swift,objc">or `embedded`</If><If lang="javascript,nodejs">or `other`</If> | String |
 | <If lang="javascript,nodejs,java,android,php,ruby,swift,objc">metadata</If> | optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | <If lang="javascript,nodejs,java,android,swift,objc">Object</If><If lang="php">Array</If><If lang="ruby">Hash</If> |
 | <If lang="javascript,nodejs,java,android,php,ruby,swift,objc">platform</If> | platform of the push device. Must be one of `ios` <If lang="javascript,nodejs,java,android,php,ruby,swift,objc">or `android`</If><If lang="javascript,nodejs">or `browser`</If> | String |
@@ -1210,7 +1210,7 @@ Failure to retrieve the message history will raise an [`AblyException`](/docs/ap
 
 ### <If lang="javascript,nodejs,php">PushChannelSubscription</If><If lang="ruby">Ably::Models::PushChannelSubscription</If><If lang="java,android">ChannelSubscription</If><If lang="swift,objc">ARTPushChannelSubscription</If> <a id="push-channel-subscription" />
 
-An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications.
+An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/platform/auth/identified-clients) to a channel in order to receive push notifications.
 
 #### <If lang="javascript,nodejs,java,android,php,swift,objc">Properties</If><If lang="ruby">Attributes</If>
 
@@ -1218,7 +1218,7 @@ An `PushChannelSubscription` is a type encapsulating the subscription of a devic
 |----------|-------------|------|
 | channel | the channel that this push notification subscription is associated with | String |
 | <If lang="javascript,nodejs,java,android,php,swift,objc">deviceId</If><If lang="ruby">device_id</If> | the device with this identifier is linked to this channel subscription. When present, <If lang="javascript,nodejs,java,android,php,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If> is never present | String |
-| <If lang="javascript,nodejs,java,android,php,swift,objc">clientId</If><If lang="ruby">client_id</If> | devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, <If lang="javascript,nodejs,java,android,php,swift,objc">`deviceId`</If><If lang="ruby">`device_id`</If> is never present | String |
+| <If lang="javascript,nodejs,java,android,php,swift,objc">clientId</If><If lang="ruby">client_id</If> | devices with this [client identifier](/docs/platform/auth/identified-clients) are included in this channel subscription. When present, <If lang="javascript,nodejs,java,android,php,swift,objc">`deviceId`</If><If lang="ruby">`device_id`</If> is never present | String |
 
 <If lang="java,android,php,ruby,swift,objc">
 
@@ -1265,14 +1265,14 @@ A [`PushChannelSubscription`](/docs/api/realtime-sdk/types#push-channel-subscrip
 
 </If>
 
-A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/auth/identified-clients).
+A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](/docs/platform/auth/identified-clients).
 
 ##### Parameters
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
 | channel | channel name linked to this push channel subscription | String |
-| <If lang="javascript,nodejs,java,android,php,swift,objc">clientId</If><If lang="ruby">client_id</If> | devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | String |
+| <If lang="javascript,nodejs,java,android,php,swift,objc">clientId</If><If lang="ruby">client_id</If> | devices with this [client identifier](/docs/platform/auth/identified-clients) are included in the new push channel subscription | String |
 
 ##### Returns
 
diff --git a/src/pages/docs/api/rest-sdk/types.mdx b/src/pages/docs/api/rest-sdk/types.mdx
index 646ef6c8f3..ac85e8d02c 100644
--- a/src/pages/docs/api/rest-sdk/types.mdx
+++ b/src/pages/docs/api/rest-sdk/types.mdx
@@ -1353,8 +1353,8 @@ Please note that `key` and `value` attributes are always strings. If an `Integer
 | <If lang="javascript,nodejs,flutter,java,objc,swift,php,ruby,python">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,flutter,java,objc,swift,php,ruby,python">expires</If><If lang="csharp,go">Expires</If> | <If lang="javascript,nodejs,flutter,java,php,python">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,flutter,php,python">`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,flutter,java,objc,swift,php,ruby,python">issued</If><If lang="csharp,go">Issued</If> | <If lang="javascript,nodejs,flutter,java,php,python">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,flutter,php,python">`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,flutter,java,objc,swift,php,ruby,python">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,flutter,java,objc,swift,php,ruby,python,go">`String`</If><If lang="csharp">`Capability`</If> |
-| <If lang="javascript,nodejs,flutter,java,objc,swift,php">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="javascript,nodejs,flutter,java,objc,swift,php,ruby,python">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/platform/auth/capabilities) | <If lang="javascript,nodejs,flutter,java,objc,swift,php,ruby,python,go">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,flutter,java,objc,swift,php">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/platform/auth/identified-clients) | `String` |
 
 <If lang="ruby">
 
@@ -1438,7 +1438,7 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object
 | <If lang="javascript,nodejs,flutter,objc,swift,php,java">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,flutter,objc,swift,php,java,ruby,python,go">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,flutter,objc,swift,php,java,python">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,flutter,php,java,python,ruby,go">`Integer`</If><If lang="csharp">`TimeSpan`</If><If lang="swift,objc">`NSTimeInterval`</If> |
 | <If lang="javascript,nodejs,flutter,objc,swift,php,java,ruby,python">timestamp</If><If lang="csharp,go">Timestamp</If> | The timestamp of this request<If lang="javascript,nodejs,flutter,objc,swift,php,java,python"> in milliseconds</If> | <If lang="javascript,nodejs,flutter,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,flutter,objc,swift,php,java,ruby,python">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,flutter,objc,swift,php,java,ruby,python">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/platform/auth) | `String` |
 | <If lang="javascript,nodejs,flutter,objc,swift,php,java">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,flutter,objc,swift,php,java,ruby,python">nonce</If><If lang="csharp,go">Nonce</If> | An opaque nonce string of at least 16 characters | `String` |
 | <If lang="javascript,nodejs,flutter,objc,swift,php,java,ruby,python">mac</If><If lang="csharp,go">Mac</If> | The Message Authentication Code for this request | `String` |
@@ -1772,27 +1772,27 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 <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:
+`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is a Hash object and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is a Dict and is used when making [authentication](/docs/platform/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:
+`AuthOptions` is an Associative Array and is used when making [authentication](/docs/platform/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,swift,objc,go">
 
-<If lang="swift,objc">`ART`</If>`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 lang="swift,objc">`ART`</If>`AuthOptions` is used when making [authentication](/docs/platform/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated.
 
 </If>
 
@@ -1800,15 +1800,15 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,objc,swift,csharp,go">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> 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,flutter,php,objc,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If><If lang="csharp">`Func<TokenParams, Task<object>>`</If><If lang="python">`Callable`</If> |
+| <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,objc,swift,csharp,go">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> 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | <If lang="javascript,nodejs,flutter,php,objc,swift,go">`Callable`</If><If lang="java">`TokenCallback`</If><If lang="ruby">`Proc`</If><If lang="csharp">`Func<TokenParams, Task<object>>`</If><If lang="python">`Callable`</If> |
 | <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,java,ruby,python,go">`String`</If><If lang="csharp">`Uri`</If><If lang="swift,objc">`NSURL`</If> |
 | <If lang="javascript,nodejs,flutter,php,java,objc,swift">authMethod</If><If lang="csharp,go">AuthMethod</If><If lang="python">auth_method</If><If lang="ruby">:auth_method</If> | The HTTP verb to use for the request, either <If lang="javascript,nodejs,flutter,php,java,objc,swift,python,csharp,go">`GET`</If><If lang="ruby">`:get`</If> or <If lang="javascript,nodejs,flutter,php,java,objc,swift,python,csharp,go">`POST`</If><If lang="ruby">`:post`</If>. The default is <If lang="javascript,nodejs,flutter,php,java,objc,swift,python,csharp,go">`GET`</If><If lang="ruby">`:get`</If>. | <If lang="javascript,nodejs,flutter,php,java,objc,swift,python,go">`String`</If><If lang="ruby">`Symbol`</If><If lang="csharp">`HttpMethod`</If> |
 | <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,java,objc,swift,python,ruby,go">`authUrl`</If><If lang="csharp">`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">`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="flutter">`Map<String, String>`</If><If lang="go">`Object`</If> |
 | <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,java,objc,swift,python,ruby">`authUrl`</If><If lang="csharp">`AuthUrl`</If>. When the <If lang="javascript,nodejs,flutter,php,java,objc,swift,python,ruby">`authMethod`</If><If lang="csharp,go">`AuthMethod`</If> is `GET`, query params are added to the URL, whereas when <If lang="javascript,nodejs,flutter,php,java,objc,swift,python,ruby">`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">`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="flutter">`Map<String, String>`</If><If lang="python">`Object`</If><If lang="go">`Object`</If> |
-| <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,java,objc,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,flutter,php,java,objc,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,flutter,php,java,objc,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,flutter,php,java,objc,swift">queryTime</If><If lang="csharp,go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | 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. The default is false. | `Boolean` |
-| <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,java,objc,swift,python">`token`</If><If lang="csharp,go">`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,flutter,php,java,objc,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,flutter,php,java,objc,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,flutter,php,java,objc,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,flutter,php,java,objc,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,flutter,php,java,objc,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/platform/auth/token) | `TokenDetails` |
+| <If lang="javascript,nodejs,flutter,php,java,objc,swift">key</If><If lang="csharp,go">Key</If><If lang="ruby">:key</If><If lang="python">key</If> | Optionally the [API key](/docs/platform/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,flutter,php,java,objc,swift">queryTime</If><If lang="csharp,go">QueryTime</If><If lang="ruby">:query_time</If><If lang="python">query_time</If> | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/platform/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. The default is false. | `Boolean` |
+| <If lang="javascript,nodejs,flutter,php,java,objc,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,flutter,php,java,objc,swift,python">`token`</If><If lang="csharp,go">`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/platform/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,flutter,php,java,objc,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,flutter,php,java,objc,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/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
 
 
 ### <If lang="javascript,nodejs,flutter,python,go">ClientOptions Object</If><If lang="objc,swift">ARTClientOptions</If><If lang="ruby">ClientOptions Hash</If><If lang="php">ClientOptions Array</If><If lang="java">io.ably.types.ClientOptions</If><If lang="csharp">IO.Ably.ClientOptions</If> <a id="client-options" />
@@ -1845,17 +1845,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | 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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function<If lang="javascript,nodejs">function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))`</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. | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | 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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function<If lang="javascript,nodejs">function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))`</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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | authUrl | 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. | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. 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> | `Object` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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. | `Object` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
@@ -1865,7 +1865,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | logHandler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` |
 | transports | An optional array of transports to use, in descending order of preference. <If lang="javascript">In the browser environment the available transports are: `web_socket`, `xhr_polling`.</If><If lang="nodejs">The transports available in the Node.js client library are: `web_socket`, `xhr_polling`, `comet`.</If> | `String []` |
 | useBinaryProtocol | <If lang="javascript">If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). The default is false.</If><If lang="nodejs">If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true.</If> Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| queryTime | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 
@@ -1874,17 +1874,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | 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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A `TokenCallback` instance 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. | `TokenCallback` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | 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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A `TokenCallback` instance 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `TokenCallback` |
 | authUrl | 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. | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Param []` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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. | `Param[]` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is Null. | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is Null. | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
@@ -1893,7 +1893,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | logLevel | A number controlling the verbosity of the output from 2 (maximum, verbose) to 6 (errors only). A special value of 99 will silence all logging. Note that the `logLevel` is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See [the logging section of the java library README](https://github.com/ably/ably-java/#logging) for more details. The default is 5. | `Integer` |
 | logHandler | A `LogHandler` interface can be specified to handle each line of log output. If `logHandler` is not specified, `System.out` is used. Note that the `logHandler` is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See [the logging section of the java library README](https://github.com/ably/ably-java/#logging) for more details. The default is `System.out PrintStream`. | `PrintStream` |
 | useBinaryProtocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| queryTime | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -1901,17 +1901,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| Token | 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 `Token` 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| AuthCallback | A function 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. | `Func<TokenParams, Task<object>>` |
+| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| Token | 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 `Token` 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/platform/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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| AuthCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Func<TokenParams, Task<object>>` |
 | AuthUrl | 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. | `Uri` |
 | AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `HttpMethod` |
 | AuthHeaders | A set of key value pair headers to be added to any request made to the `AuthUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Dictionary<string, string>` |
 | AuthParams | A set of key value pair params to be added to any request made to the `AuthUrl`. When the `AuthMethod` is `GET`, query params are added to the URL, whereas when `AuthMethod` 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. | `Dictionary<string, string>` |
-| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | Tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| UseTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | IdempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
@@ -1920,7 +1920,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | LogLevel | This is an enum controlling the verbosity of the output from `Debug` (maximum) to `Error` (errors only). A special value of `None` will silence all logging. Note that the `LogLevel` is a static variable in the library and will thus not act independently between library instances. The default is `Error`. | `Enum` |
 | LoggerSink | The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure. The default is `IO.Ably.DefaultLoggerSink`. | |
 | UseBinaryProtocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| QueryTime | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | DefaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -1928,17 +1928,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| Token | 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 `Token` 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| AuthCallback | A function 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. | `Callable` |
+| Key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| Token | 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 `Token` 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/platform/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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| AuthCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | AuthUrl | 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. | `String` |
 | AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` |
 | AuthHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Object` |
 | AuthParams | A set of key value pair params to be added to any request made to the `AuthUrl`. When the `AuthMethod` is `GET`, query params are added to the URL, whereas when `AuthMethod` 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. | `Object` |
-| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| TokenDetails | 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | Tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| UseTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | IdempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
@@ -1946,7 +1946,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object` |
 | LogLevel | This is an enum controlling the verbosity of the output from `LogDebug` (maximum) to `LogError` (errors only). A special value of `LogNone` will silence all logging. Note that the `LogLevel` is a static variable in the library and will thus not act independently between library instances. The default is `LogError`. | `Enum` |
 | UseBinaryProtocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| QueryTime | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | DefaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -1954,17 +1954,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | 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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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. | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | 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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | authUrl | 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. | `NSURL` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Object` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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="objc">`NSArray<NSURLQueryItem *>`</If><If lang="swift">`[NSURLQueryItem]/Array<NSURLQueryItem>`</If> |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is nil. | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is nil. | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
@@ -1974,7 +1974,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | logHandler | A `ARTLog` object can be specified to handle each line of log output. If `logHandler` is not specified, a default `ARTLog` instance is used. | `ARTLog *` |
 | useBinaryProtocol | Note: The binary protocol is currently not supported <If lang="swift">in Swift</If><If lang="objc">in Objective-C</If>. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
 | logExceptionReportingUrl | Defaults to a string value for an Ably error reporting Data Source Name. | `String` |
-| queryTime | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -1982,17 +1982,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| :token | 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 `token` 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 `:auth_url` or `:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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. | `Proc` |
+| :key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| :token | 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 `token` 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/platform/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 `:auth_url` or `:auth_callback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Proc` |
 | :auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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. | `String` |
 | :auth_method | The HTTP verb to use for the request, either `:get` or `:post`. The default is `:get`. | `Symbol` |
 | :auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Hash` |
 | :auth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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. | `Hash` |
-| :token_details | 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 `:auth_url` or `:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| :token_details | 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 `:auth_url` or `:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | :tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| :use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| :use_token_auth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | :endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is nil. | `String` |
 | :environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is nil. | `String` |
 | :idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
@@ -2001,7 +2001,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | :log_level | Log level for the standard Logger that outputs to `STDOUT`. Can be set to `:fatal`, `:error`, `:warn`, `:info`, `:debug` or `:none`. Alternatively a [`Logger` severity constant](http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-Description) can be specified. The default is `:error`. | `Symbol`, [`Logger::SEVERITY`](http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-Description) |
 | :logger | A [Ruby `Logger`](http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html) compatible object to handle each line of log output. If `logger` is not specified, `STDOUT` is used. The default is `STDOUT Logger`. | [Ruby `Logger`](http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html) |
 | :use_binary_protocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| :query_time | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | :default_token_params | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -2009,17 +2009,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | 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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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. | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | 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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | authUrl | 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. | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | Associative Array |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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. | Associative Array |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
@@ -2028,7 +2028,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 | logLevel | A number controlling the verbosity of the output from 1 (minimum, errors only) to 4 (most verbose). The default is `Log::WARNING`. | `Integer` |
 | logHandler | A function to handle each line of log output. If handler is not specified, `console.log` is used. Note that the log level and log handler have global scope in the library and will therefore not act independently between library instances when multiple library instances exist concurrently. The default is `console.log`. | `Function` |
 | useBinaryProtocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Note: The binary protocol is currently not supported in PHP. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| queryTime | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -2036,24 +2036,24 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | 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 `token` 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 `auth_url` or `auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| auth_callback | A callable (eg a lambda) 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. | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | 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 `token` 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/platform/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 `auth_url` or `auth_callback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| auth_callback | A callable (eg a lambda) 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/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. | `String` |
 | auth_method | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` |
 | auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Dict` |
 | auth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `auth_method` is `GET`, query params are added to the URL, whereas when `auth_method` 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. | `Object` |
-| token_details | 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 `auth_url` or `auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| token_details | 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 `auth_url` or `auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `client_id` 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 `client_id` may also be implicit in a token used to instantiate the library; an error will be raised if a `client_id` specified here conflicts with the `client_id` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| use_token_auth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is None. | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is None. | `String` |
 | idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
 | fallback_hosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here. The default is `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`. | `String []` |
 | transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Dict` |
 | use_binary_protocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| query_time | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | default_token_params | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -2062,24 +2062,24 @@ A `TokenRevocationFailureResult` contains information about the result of an uns
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` |
-| token | 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 `token` 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
-| authCallback | A function 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. | `Callable` |
+| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/platform/auth/basic) | `String` |
+| token | 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 `token` 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/platform/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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/platform/auth/token) | `String`, `TokenDetails` or `TokenRequest` |
+| authCallback | A function 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/platform/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` |
 | authUrl | 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. | `String` |
 | authMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` |
 | authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Map<String, String>` |
 | authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` 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. | `Map<String, String>` |
-| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` |
+| tokenDetails | 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/platform/auth/token) | `TokenDetails` |
 | tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` |
-| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` |
-| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
+| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/platform/auth/identified-clients) | `String` |
+| useTokenAuth | When true, forces [Token authentication](/docs/platform/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` |
 | endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` |
 | idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default. The default is false. | `Boolean` |
 | fallbackHosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here. The default is `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`. | `String []` |
 | transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Map<String, String>` |
 | useBinaryProtocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` |
-| queryTime | 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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
+| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/platform/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/api/rest-sdk/authentication#token-request), 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. The default is false. | `Boolean` |
 | defaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) |
 
 </If>
@@ -2215,32 +2215,32 @@ Individual client libraries may support either instancing a `CipherParams` direc
 
 <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:
+`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is a Dict and is used in the parameters of [token authentication](/docs/platform/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:
+`TokenParams` is an Associative Array and is used in the parameters of [token authentication](/docs/platform/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">
 
-`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).
+`TokenParams` is used in the parameters of [token authentication](/docs/platform/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).
+`ARTTokenParams` is used in the parameters of [token authentication](/docs/platform/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details).
 
 </If>
 
@@ -2248,8 +2248,8 @@ Individual client libraries may support either instancing a `CipherParams` direc
 
 | Parameter | Description | Type |
 |-----------|-------------|------|
-| <If lang="javascript,nodejs,flutter,php,objc,swift,java,python">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,flutter,php,objc,swift,java,python,ruby,go">`String`</If><If lang="csharp">`Capability`</If> |
-| <If lang="javascript,nodejs,flutter,php,objc,swift,java">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,flutter,php,objc,swift,java">`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,flutter,php,objc,swift,java">`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,flutter,php,objc,swift,java">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="csharp,go">`ClientId`</If> specified here conflicts with the <If lang="javascript,nodejs,flutter,php,objc,swift,java">`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,flutter,php,objc,swift,java,python">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/platform/auth/capabilities). | <If lang="javascript,nodejs,flutter,php,objc,swift,java,python,ruby,go">`String`</If><If lang="csharp">`Capability`</If> |
+| <If lang="javascript,nodejs,flutter,php,objc,swift,java">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,flutter,php,objc,swift,java">`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,flutter,php,objc,swift,java">`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,flutter,php,objc,swift,java">`clientId`</If><If lang="ruby,python">`client_id`</If><If lang="csharp,go">`ClientId`</If> specified here conflicts with the <If lang="javascript,nodejs,flutter,php,objc,swift,java">`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/platform/auth/identified-clients) | `String` |
 | <If lang="javascript,nodejs,flutter,php,objc,swift,java,python">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,flutter,php,objc,swift,java,python">timestamp</If><If lang="csharp,go">Timestamp</If><If lang="ruby">:timestamp</If> | <If lang="javascript,nodejs,flutter,php,go,java,python">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,objc,swift,python">`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="flutter">`DateTime`</If> |
 | <If lang="javascript,nodejs,flutter,php,objc,swift,java,python">ttl</If><If lang="csharp,go">Ttl</If><If lang="ruby">:ttl</If> | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created <If lang="javascript,nodejs,flutter,php,go,java,python">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. The default is 1 hour. | <If lang="javascript,nodejs,flutter,php,python">`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> |
diff --git a/src/pages/docs/api/token-request-spec.mdx b/src/pages/docs/api/token-request-spec.mdx
index 5f447a50d4..52143f1526 100644
--- a/src/pages/docs/api/token-request-spec.mdx
+++ b/src/pages/docs/api/token-request-spec.mdx
@@ -9,7 +9,7 @@ redirect_from:
   - /docs/rest-api/versions/v1.0/token-request-spec
 ---
 
-The [Ably REST and Realtime client libraries](https://ably.com/download/) aim to make things as simple as possible so it is not necessary to understand all of the details of how to interact with the service and issue tokens for clients. If you wish to issue Ably-compatible tokens or [Ably TokenRequests](/docs/api/realtime-sdk/types#token-request), we recommend you start with the [client library authentication documentation](/docs/auth).
+The [Ably REST and Realtime client libraries](https://ably.com/download/) aim to make things as simple as possible so it is not necessary to understand all of the details of how to interact with the service and issue tokens for clients. If you wish to issue Ably-compatible tokens or [Ably TokenRequests](/docs/api/realtime-sdk/types#token-request), we recommend you start with the [client library authentication documentation](/docs/platform/auth).
 
 However, if you are using the [REST API token endpoint directly](/docs/api/rest-api/#request-token), or if you are creating Ably `TokenRequests` without the use of our client libraries, then the following specification will give you an in-depth understanding of how getting Ably Tokens works.
 
@@ -81,9 +81,9 @@ The following capability operations are available for API keys and issued tokens
 | channel-metadata | Can get metadata for a channel, and enumerate channels |
 | privileged-headers | Can set data in the privileged section of the [message extras](/docs/api/realtime-sdk/messages#extras) |
 
-Read the [capabilities docs](/docs/auth/capabilities) to get a more thorough overview of how capabilities can be used to secure your application.
+Read the [capabilities docs](/docs/platform/auth/capabilities) to get a more thorough overview of how capabilities can be used to secure your application.
 
-While most of these capabilities need to be enabled for the resource you're using them with, as described in [resource names and wildcards](/docs/auth/capabilities#wildcards), there are exceptions. The `stats` permission only does something when attached to the wildcard resource `'*'`, or a resource that contains that as a subset, such as `'[*]*'`, since stats are app-wide.
+While most of these capabilities need to be enabled for the resource you're using them with, as described in [resource names and wildcards](/docs/platform/auth/capabilities#wildcards), there are exceptions. The `stats` permission only does something when attached to the wildcard resource `'*'`, or a resource that contains that as a subset, such as `'[*]*'`, since stats are app-wide.
 
 The `channel-metadata` permission works both ways. When associated with a specific channel or set of channels it allows you to [query the metadata of a channel](/docs/metadata-stats/metadata/rest) to request its status. When associated with the wildcard resource `'*'` it takes on an additional meaning: as well as allowing channel status requests for all channels, it also allows you to [enumerate all active channels](/docs/metadata-stats/metadata/rest#enumerate).
 
diff --git a/src/pages/docs/auth/identified-clients.mdx b/src/pages/docs/auth/identified-clients.mdx
deleted file mode 100644
index e4754fa566..0000000000
--- a/src/pages/docs/auth/identified-clients.mdx
+++ /dev/null
@@ -1,218 +0,0 @@
----
-title: Identified clients
-meta_description: "Clients can be allocated a client ID to help control their operations and interactions with Ably channels."
----
-
-When a client is authenticated and connected to Ably, it is considered to be an authenticated client. While an authenticated client has a means to authenticate with Ably, they do not necessarily have an identity.
-
-When a client is assigned a trusted identity, that is, a `clientId`, then they are considered to be an identified client. For all operations that client performs with the Ably service, their `clientId` field will be automatically populated and can be trusted by other clients.
-
-For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a `clientId` that they are not assigned in their Ably-compatible token. They are unable to masquerade as another `clientId`.
-
-## ClientId immutability <a id="immutability"/>
-
-A connection's `clientId`, once set, is immutable. You cannot change a `clientId` after it has been established for a connection.
-
-### Late initialization
-
-It is possible to have late initialization of `clientId` in certain scenarios:
-
-* AuthCallback discovery: When using `authCallback`, the `clientId` may only become known when the first authCallback completes and returns a token with a `clientId`.
-* Opaque token processing: When the library receives an opaque token string, it only learns the `clientId` when it receives a response from the server that has processed the token.
-
-In both cases, the immutability requirement is satisfied because the `clientId` gets set as part of the client's first interaction with the server. Once this initial authentication is complete, the `clientId` cannot be changed for that connection.
-
-## Assign a clientId <a id="assign"/>
-
-There are three different ways a client can be identified with using a `clientId`:
-
-* A client claims a `clientId` when authenticating with an API key.
-* A client is authenticating with a token issued for a specific `clientId`.
-* A client claims a `clientId` when authenticating with a token that is issued for a wildcard `clientId`.
-
-When a client sets their own ID there is the possibility that they can pretend to be someone else. To prevent this, it is recommended that you embed a `clientId` in the token issued to your clients from your auth server. This ensures that the `clientId` is set by your auth server, and eliminates the chance of a client pretending to be someone else.
-
-<Aside data-type='note'>
-Identifying a client varies depending on whether they are authenticating with basic authentication or token authentication. Token authentication is [recommended](/docs/auth#selecting-auth) in most instances so that clients authenticate using short-lived tokens and do not have access to API keys.
-
-Since you then control the `clientId`, all other clients can rely on the validity of the `clientId` in published messages and of members present in presence channels. This eliminates the possibility of a client pretending to be someone else, as they cannot claim a `clientId` in their own.
-</Aside>
-
-### Basic auth <a id="basic"/>
-
-You can use [basic authentication](/docs/auth/basic) to allow a client to claim any `clientId` when they authenticate with Ably. As the assignation of the `clientId` is not handled by a server, it cannot be trusted to represent the genuine identity of the client.
-
-### Token auth <a id="token"/>
-
-You can use [token authentication](/docs/auth/token) to set an explicit `clientId` when creating or issuing a token. Clients using that token are restricted to operations for only that `clientId`, and all operations will implicitly contain that `clientId`.
-
-For example, when publishing a message, the `clientId` attribute of the message will be pre-populated with that `clientId`. Entering presence will also implicitly use that `clientId`.
-
-The following example demonstrates how to issue an [Ably TokenRequest](/docs/auth/token#token-request) with an explicit `clientId`:
-
-<Code>
-```realtime_javascript
-  const realtime = new Ably.Realtime({ key: '{{API_KEY}}' });
-  const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'Bob'});
-```
-
-```realtime_nodejs
-  const realtime = new Ably.Realtime({ key: '{{API_KEY}}' });
-  const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'Bob'});
-```
-
-```realtime_ruby
-  realtime = Ably::Realtime.new(key: '{{API_KEY}}')
-  realtime.auth.createTokenRequest(client_id: 'Bob') do |token_request|
-    # ... issue the TokenRequest to a client ...
-  end
-```
-
-```realtime_python
-  realtime = AblyRealtime(key='{{API_KEY}}')
-  token_request = await realtime.auth.create_token_request({'client_id': 'Bob'})
-  # ... issue the TokenRequest to a client ...
-```
-
-```realtime_java
-  ClientOptions options = new ClientOptions();
-  options.key = "{{API_KEY}}";
-  AblyRealtime realtime = new AblyRealtime(options);
-  TokenParams tokenParams = new TokenParams();
-  tokenParams.clientId = "Bob";
-  TokenRequest tokenRequest;
-  tokenRequest = realtime.auth.createTokenRequest(tokenParams, null);
-  /* ... issue the TokenRequest to a client ... */
-```
-
-```realtime_csharp
-  AblyRealtime realtime = new AblyRealtime("{{API_KEY}}");
-  TokenParams tokenParams = new TokenParams {ClientId = "Bob"};
-  string tokenRequest = await realtime.Auth.CreateTokenRequestAsync(tokenParams);
-  /* ... issue the TokenRequest to a client ... */
-```
-
-```realtime_objc
-  ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
-  ARTTokenParams *tokenParams = [[ARTTokenParams alloc] initWithClientId:@"Bob"];
-  [realtime.auth createTokenRequest:tokenParams options:nil
-                 callback:^(ARTTokenRequest *tokenRequest NSError *error) {
-      // ... issue the TokenRequest to a client ...
-  }];
-```
-
-```realtime_swift
-  let realtime = ARTRealtime(key: "{{API_KEY}}")
-  let tokenParams = ARTTokenParams(clientId: "Bob")
-  realtime.auth.createTokenRequest(tokenParams, options: nil) { tokenRequest, error in
-      // ... issue the TokenRequest to a client ...
-  }
-```
-
-```realtime_go
-realtime, _ := ably.NewRealtime(
-  ably.WithKey("{{API_KEY}}"))
-params := &ably.TokenParams{
-  ClientID: "Bob",
-}
-tokenRequest, _ := realtime.Auth.CreateTokenRequest(params)
-```
-
-```realtime_flutter
-final realtime = ably.Realtime(options: ably.ClientOptions(key: '{{API_KEY}}'));
-final tokenRequest = await realtime.auth.createTokenRequest(
-  tokenParams: ably.TokenParams(clientId: 'Bob'),
-);
-```
-
-```rest_javascript
-  const rest = new Ably.Rest({ key: '{{API_KEY}}' });
-  const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'Bob'});
-```
-
-```rest_nodejs
-  const rest = new Ably.Rest({ key: '{{API_KEY}}' });
-  const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'Bob'});
-```
-
-```rest_ruby
-  rest = Ably::Rest.new(key: '{{API_KEY}}')
-  token_request = rest.auth.create_token_request(client_id: 'Bob')
-  # ... issue the TokenRequest to a client ...
-```
-
-```rest_python
-  rest = AblyRest(key='{{API_KEY}}')
-  token_request = await rest.auth.create_token_request({'client_id': 'Bob'})
-  # ... issue the TokenRequest to a client ...
-```
-
-```rest_php
-  $rest = new Ably\AblyRest(
-    ['key' => '{{API_KEY}}']
-  );
-  $tokenRequest = $rest->auth->createTokenRequest(
-    ['clientId' => 'Bob']
-  );
-  // ... issue the TokenRequest to a client ...
-```
-
-```rest_java
-  ClientOptions options = new ClientOptions();
-  options.key = "{{API_KEY}}";
-  AblyRest rest = new AblyRest(options);
-  TokenParams tokenParams = new TokenParams();
-  tokenParams.clientId = "Bob";
-  TokenRequest tokenRequest;
-  tokenRequest = rest.auth.createTokenRequest(tokenParams, null);
-  /* ... issue the TokenRequest to a client ... */
-```
-
-```rest_csharp
-  AblyRest rest = new AblyRest(new ClientOptions {Key = "{{API_KEY}}"});
-  TokenParams tokenParams = new TokenParams {ClientId = "Bob"};
-  string tokenRequest = await rest.Auth.CreateTokenRequestAsync(tokenParams);
-  // ... issue the TokenRequest to a client ...
-```
-
-```rest_objc
-  ARTRest *rest = [[ARTRest alloc] initWithKey:@"{{API_KEY}}"];
-  ARTTokenParams *tokenParams = [[ARTTokenParams alloc] initWithClientId:@"Bob"];
-  [rest.auth createTokenRequest:tokenParams options:nil
-    callback:^(ARTTokenRequest *tokenRequest, NSError *error) {
-      // ... issue the TokenRequest to a client ...
-  }];
-```
-
-```rest_swift
-  let rest = ARTRest(key: "{{API_KEY}}")
-  let tokenParams = ARTTokenParams(clientId: "Bob")
-  rest.auth.createTokenRequest(tokenParams, options: nil) { tokenRequest, error in
-    // ... issue the TokenRequest to a client ...
-  }
-```
-
-```rest_go
-rest, _ := ably.NewREST(
-  ably.WithKey("{{API_KEY}}"))
-params := &ably.TokenParams{
-  ClientID: "Bob",
-}
-tokenRequest, _ := rest.Auth.CreateTokenRequest(params)
-```
-
-```rest_flutter
-final rest = ably.Rest(options: ably.ClientOptions(key: '{{API_KEY}}'));
-final tokenRequest = await rest.auth.createTokenRequest(
-  tokenParams: ably.TokenParams(clientId: 'Bob'),
-);
-```
-</Code>
-
-### Wildcard token auth <a id="wildcard"/>
-
-You can use [token authentication](/docs/auth/token) to set a wildcard `clientId` using a value of `*` when creating a token. Clients are then able to assume any identity in their operations, such as when publishing a message or entering presence.
-
-## Unidentified clients <a id="unidentified"/>
-
-If no `clientId` is provided when using [token authentication](/docs/auth/token) then clients are not permitted to assume an identity and will be considered an unidentified client in all operations. Messages published will contain no `clientId` and those clients will not be permitted to enter the [presence](/docs/presence-occupancy/presence) set.
diff --git a/src/pages/docs/auth/index.mdx b/src/pages/docs/auth/index.mdx
deleted file mode 100644
index 51949e95e5..0000000000
--- a/src/pages/docs/auth/index.mdx
+++ /dev/null
@@ -1,110 +0,0 @@
----
-title: Authentication overview
-meta_description: "Ably supports two main authentication schemes: basic authentication and token authentication. Token authentication can be implemented using JWTs, Ably tokens, and Ably token requests."
-redirect_from:
-  - /docs/rest/authentication
-  - /docs/rest/versions/v1.1/authentication
-  - /docs/rest/versions/v1.0/authentication
-  - /docs/rest/versions/v0.8/authentication
-  - /docs/realtime/authentication
-  - /docs/realtime/versions/v1.1/authentication
-  - /docs/realtime/versions/v1.0/authentication
-  - /docs/realtime/versions/v0.8/authentication
-  - /docs/core-features/authentication
-  - /docs/core-features/versions/v1.1/authentication
-  - /docs/core-features/versions/v1.0/authentication
-  - /docs/core-features/versions/v0.8/authentication
-  - /docs/core-features/authentication.ably-jwt
-  - /docs/general/authentication
-  - /docs/general/_authentication_capabilities
-  - /docs/ids-and-keys
----
-
-Before a client or server can issue requests to Ably, such as subscribe to channels, or publish messages, it must authenticate with Ably. Authentication requires an Ably API key.
-
-## Authentication terminology <a id="terminology"/>
-
-The following terminology helps explain authentication, authorization, and identification in the context of the Ably service:
-
-"Authentication" is the process of deciding, based on the presented credentials, whether or not an entity may interact with the Ably service. The credentials may be presented explicitly using [Basic Authentication](/docs/auth/basic) or [Token Authentication](/docs/auth/token), or in some cases the entity authenticating may prove possession of the credentials with a signed Token Request that is subsequently used to generate a valid token to be used for Token Authentication. When authenticating with Ably, the credentials are either an API key or an auth token.
-
-"Authenticated client" is a client of the Ably service that has been successfully authenticated.
-
-"Authorization" is the process of deciding whether or not a given entity (usually authenticated) is allowed to perform a given operation. In Ably, authorization for most operations is based on the [capabilities](/docs/auth/capabilities) associated with the key or token that was used to authenticate a client.
-
-"Identified client" is an authenticated client with a specific claimed client identity, or `clientId`, whose credentials are verified as confirming that identity. See the [identified clients](/docs/auth/identified-clients) documentation for more information.
-
-<Aside data-type='note'>
-Channels can be configured to only allow [identified clients](/docs/auth/identified-clients). Learn more about [channel rules](/docs/channels#rules).
-</Aside>
-
-## Ably API keys <a id="api-keys"/>
-
-Every Ably app can have one or more API keys associated with it in order to authenticate directly with Ably, or to issue tokens with. API keys can be created with different [capabilities](/docs/auth/capabilities) and any tokens issued using that API key can only permit a subset of those capabilities.
-
-### API key format <a id="format"/>
-
-An Ably API key string has the following format: `I2E_JQ.OqUdfg:EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0`.
-
-The API key is made up of three parts:
-
-1. `I2E_JQ` is the public app ID (the part before the first period)
-2. `OqUdfg` is the public app key ID (the part after the period and before the colon). `I2E_JQ.OqUdfg` is the public API key ID (both the public app ID and app key ID together)
-3. `EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0` is the API key secret and should never be shared with untrusted parties (the part after the colon)
-
-The API key secret is private and should never be made public. This API key string is used in all Ably SDKs and for authentication with the REST API.
-
-### Create an API key <a id="create"/>
-
-API keys are created in the [Ably dashboard](https://ably.com/dashboard). You can also create an API key programmatically using the [Control API](/docs/platform/account/control-api).
-
-To create an API key in the Ably dashboard:
-
-1. In your [Ably dashboard](https://ably.com/dashboard) click the API Keys tab.
-2. Click the **Create a new API key** button.
-3. Enter a name for your API key - this will help you identify the specific key when you have many keys created.
-4. Select the [capabilities](/docs/auth/capabilities) you want to apply to the key. Clients connecting with this key will be restricted to these capabilities.
-5. Optionally you can select whether to make tokens generated from this key to be revocable or not.
-6. Optionally select whether you want to restrict the scope of the key to channels, queues, or specific channels and queues using resource names and wildcards.
-
-<Aside data-type="important">
-Many of the code samples used throughout the documentation use basic authentication to demonstrate features for convenience. It should be stressed that in your own applications, you should never use [basic authentication](/docs/auth/basic) on the client-side, as it exposes your Ably API key.
-
-If you are logged into your Ably account, the code samples will be populated with your actual key for convenience. If you are not logged into Ably, a temporary key is generated for you.
-</Aside>
-
-## Available authentication mechanisms <a id="mechanisms"/>
-
-The two authentication mechanisms available to authenticate with Ably are:
-
-1. [Basic authentication](/docs/auth/basic), which uses your Ably API key directly.
-2. [Token authentication](/docs/auth/token), which uses short-lived tokens for access. These tokens are periodically renewed, and can be revoked if required.
-
-### Client-side authentication <a id="client"/>
-
-[Token authentication](/docs/auth/token) is the recommended authentication mechanism on the client-side, as it provides more fine-grained access control and limits the risk of exposing your Ably API key.
-
-In production systems you should never use basic authentication on the client-side as it exposes your Ably API key. API keys don't have an expiry, so once compromised, they could be used indefinitely by an attacker.
-
-Tokens have an expiry, and so there is only a small period of time during which the compromised token can be used. It is also possible to [revoke tokens](/docs/auth/revocation), should that be necessary for security reasons.
-
-### Server-side authentication <a id="server"/>
-
-Use [basic authentication](/docs/auth/basic) on the server-side. You should never use token authentication server-side, as this results in unnecessary overhead due the server needing to periodically make token requests to authenticate itself.
-
-## Selecting an authentication mechanism <a id="selecting-auth"/>
-
-When deciding on which authentication method you will be using, it is recommended you bear in mind the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege).
-
-A client should ideally only possess the credentials and rights that it needs to accomplish what it wants. This way, if the credentials are compromised, the rights that can be abused by an attacker are minimized.
-
-The following table provides guidelines on what to consider when choosing your authentication method. Many applications will most naturally use a mixed strategy: one or more trusted application servers will use basic authentication to access the service and issue tokens over HTTPS, whereas remote browsers and devices will use individually issued tokens:
-
-| Scenario | [Basic](/docs/auth/basic) | [Token](/docs/auth/token) | Description |
-|----------|---------------------------|---------------------------|-------------|
-| Your scripts may be exposed | No | Yes | If the script, program or system holding the key is exposed, for example on a user's device, you should not embed an API key and instead use token authentication. If the script is on a secure environment such as your own server, an API key with basic authentication is fine. |
-| Your connection may be insecure | No | Yes | If there is a risk of exposure of the client's credentials, either directly or over an insecure, or insecurely proxied, connection, token authentication should be used. If you are sure the connection is secure and unmediated, basic authentication is acceptable. |
-| You have no server to control access | Yes | No  | If you do not have your own server to perform authentication and provide tokens to users, you'll need to use basic authentication. |
-| You require fine-grained access control | No | Yes | If you need to provide [privileges](/docs/auth/capabilities) on a user-by-user basis, you'd be better using token authentication. If you only need a few access control groups, basic authentication is reasonable. |
-| Users need restricted periods of access | No | Yes | If you need users to only have access for a certain period of time, or the ability to revoke access, token authentication is needed. If users are able to always have access, basic authentication is acceptable. |
-| Users need to identify themselves | Partial  | Yes | If the user can be trusted to [identify](/docs/auth/identified-clients) itself, basic authentication is fine. If the user cannot be trusted however, token authentication is better as it allows for a trusted token distributor to identify the user instead. |
diff --git a/src/pages/docs/channels/index.mdx b/src/pages/docs/channels/index.mdx
index b0b6f0695d..b9d40218a5 100644
--- a/src/pages/docs/channels/index.mdx
+++ b/src/pages/docs/channels/index.mdx
@@ -26,7 +26,7 @@ redirect_from:
   - /docs/general/versions/v0.8/channel-rules-namespaces
 ---
 
-Channels are used to separate messages into different topics. They are the building block of creating a realtime application using the publish-subscribe pattern. Channels are also the unit of security and scalability. Clients should only ever be provided the [capabilities](/docs/auth/capabilities) for channels that they should have access to.
+Channels are used to separate messages into different topics. They are the building block of creating a realtime application using the publish-subscribe pattern. Channels are also the unit of security and scalability. Clients should only ever be provided the [capabilities](/docs/platform/auth/capabilities) for channels that they should have access to.
 
 [Messages](/docs/channels/messages) contain the data that a client is communicating, such as the contents of an individual chat message, or an event that has occurred, such as updated financial information.
 
@@ -151,17 +151,17 @@ A namespace is the first part of a channel name up to the first colon (`:`). If
 
 Channel namespaces have the same restrictions as those listed for channels. Additionally they cannot contain the wildcard character `*`.
 
-Use channel namespaces to apply operations to all channels within that group, such as [capabilities](/docs/auth/capabilities), [channel rules](#rules) and [integrations](/docs/platform/integrations).
+Use channel namespaces to apply operations to all channels within that group, such as [capabilities](/docs/platform/auth/capabilities), [channel rules](#rules) and [integrations](/docs/platform/integrations).
 
 <Aside data-type="note">
-Namespaces are not required to refer to a group of channels within a [capability](/docs/auth/capabilities). A resource specifier, such as `foo:*`, a glob expression, will match a channel named `foo:bar`, even without a `foo` namespace.
+Namespaces are not required to refer to a group of channels within a [capability](/docs/platform/auth/capabilities). A resource specifier, such as `foo:*`, a glob expression, will match a channel named `foo:bar`, even without a `foo` namespace.
 </Aside>
 
 ## Publishing and subscribing <a id="pub-sub"/>
 
 Clients [subscribe](/docs/pub-sub#subscribe) to a channel to receive the messages published to it. Clients can subscribe to all messages, or only messages identified by specific names.
 
-[Publishing](/docs/pub-sub#publish) messages to a channel is how clients communicate with one another. Any subscribers will receive published messages as long as they are subscribed and have the `subscribe` [capability](/docs/auth/capabilities) for that channel.
+[Publishing](/docs/pub-sub#publish) messages to a channel is how clients communicate with one another. Any subscribers will receive published messages as long as they are subscribed and have the `subscribe` [capability](/docs/platform/auth/capabilities) for that channel.
 
 ## Channel options <a id="options"/>
 
@@ -190,7 +190,7 @@ The channel rules related to security and client identity are:
 
 | Rule | Description |
 |------|-------------|
-| Identified | If enabled, clients will not be permitted to use (including to attach, publish, or subscribe) matching channels unless they are [identified](/docs/auth/identified-clients) (they have an assigned client ID). Anonymous clients are not permitted to join these channels. Find out more about [authenticated and identified clients](/docs/auth/identified-clients). |
+| Identified | If enabled, clients will not be permitted to use (including to attach, publish, or subscribe) matching channels unless they are [identified](/docs/platform/auth/identified-clients) (they have an assigned client ID). Anonymous clients are not permitted to join these channels. Find out more about [authenticated and identified clients](/docs/platform/auth/identified-clients). |
 | TLS only | If enabled, only clients who have connected to Ably over TLS will be allowed to use matching channels. By default all of Ably's client libraries use TLS when communicating with Ably over REST or when using Realtime transports such as Websockets. |
 
 The channel rules related to enabling features are:
diff --git a/src/pages/docs/channels/options/deltas.mdx b/src/pages/docs/channels/options/deltas.mdx
index 7e6ef52956..b1cb9fc95a 100644
--- a/src/pages/docs/channels/options/deltas.mdx
+++ b/src/pages/docs/channels/options/deltas.mdx
@@ -100,6 +100,10 @@ This will cause delta messages to be generated by the server and sent to the cli
 
 Note that in some SDKs, the `vcdiff` delta decoding library is excluded from the default distribution in order to avoid increasing the size. In these cases, it is also necessary to supply the delta decoder plugin when instantiating Ably.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
 /* Make sure to include <script src="//cdn.ably.com/lib/vcdiff-decoder.min-1.js"></script> in your head */
diff --git a/src/pages/docs/channels/options/encryption.mdx b/src/pages/docs/channels/options/encryption.mdx
index a1ba87fbdd..24bd51d3db 100644
--- a/src/pages/docs/channels/options/encryption.mdx
+++ b/src/pages/docs/channels/options/encryption.mdx
@@ -30,7 +30,7 @@ Disabling TLS is strongly discouraged and is enabled by default in all client li
 
 Unencrypted communication with Ably is **disallowed** if any of the following conditions are met:
 
-* You attempt to use [Basic Authentication](/docs/auth/basic) and thus transmit a private API key over an unencrypted connection. You are only permitted to use unencrypted connections with [Token Authentication](/docs/auth/token) as tokens expire, limiting the impact of token interception.
+* You attempt to use [Basic Authentication](/docs/platform/auth/basic) and thus transmit a private API key over an unencrypted connection. You are only permitted to use unencrypted connections with [Token Authentication](/docs/platform/auth/token) as tokens expire, limiting the impact of token interception.
 
 * You have specified that TLS is required in your [app settings](/docs/platform/account/app/settings).
 
@@ -84,6 +84,10 @@ A `key` should be a cryptographic key generated from a secure random source, 128
 
 The following is an example of setting encryption when obtaining a channel instance:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
   const realtime = new Ably.Realtime('{{API_KEY}}');
diff --git a/src/pages/docs/channels/options/index.mdx b/src/pages/docs/channels/options/index.mdx
index 775798840b..35528b1a01 100644
--- a/src/pages/docs/channels/options/index.mdx
+++ b/src/pages/docs/channels/options/index.mdx
@@ -28,6 +28,10 @@ Pass a `channelOptions` object into the call to [`get()`](/docs/api/realtime-sdk
 
 The following is an example of setting the `cipher` property to set [encryption](/docs/channels/options/encryption) when obtaining a channel instance:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
 const realtime = new Ably.Realtime('{{API_KEY}}');
@@ -261,7 +265,7 @@ const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts);
 As `occupancy` requires a channel subscription, it is only available when using the realtime interface of an Ably SDK.
 
 <Aside data-type="important">
-Clients require the `channel-metadata` [capability](/docs/auth/capabilities) to subscribe to occupancy metrics.
+Clients require the `channel-metadata` [capability](/docs/platform/auth/capabilities) to subscribe to occupancy metrics.
 </Aside>
 
 #### Subscribe to occupancy events <a id="subscribe-occupancy"/>
@@ -459,7 +463,7 @@ The available set of channel mode flags are:
 | `ANNOTATION_PUBLISH` | Can publish annotations to messages on the channel. | Yes |
 | `ANNOTATION_SUBSCRIBE` | Can subscribe to individual annotations on the channel. | No |
 
-The set of modes available to a client is determined by the set of [capabilities](/docs/auth/capabilities) granted by their token or API key.
+The set of modes available to a client is determined by the set of [capabilities](/docs/platform/auth/capabilities) granted by their token or API key.
 
 The modes granted by each capability are:
 
diff --git a/src/pages/docs/channels/options/rewind.mdx b/src/pages/docs/channels/options/rewind.mdx
index 91f4326318..23cb91d3df 100644
--- a/src/pages/docs/channels/options/rewind.mdx
+++ b/src/pages/docs/channels/options/rewind.mdx
@@ -35,6 +35,10 @@ If you have enabled the [persist last message](/docs/storage-history/storage#per
 
 The following example subscribes to a channel and retrieves the most recent message sent on it, if available:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
   const realtime = new Ably.Realtime('{{API_KEY}}');
diff --git a/src/pages/docs/channels/states.mdx b/src/pages/docs/channels/states.mdx
index 32dfca1ff7..e9e216204b 100644
--- a/src/pages/docs/channels/states.mdx
+++ b/src/pages/docs/channels/states.mdx
@@ -626,7 +626,7 @@ channel.Attach(context.Background())
 
 ### Fatal channel errors <a id="fatal-errors"/>
 
-Some classes of errors are fatal. These cause the channel to move to the `FAILED` state. Ably SDKs will not attempt any automatic recovery actions. For example, when attempting to attach to a channel, with a token that doesn't have the `subscribe` [capability](/docs/auth/capabilities) for that channel, will cause that channel to enter the `FAILED` state.
+Some classes of errors are fatal. These cause the channel to move to the `FAILED` state. Ably SDKs will not attempt any automatic recovery actions. For example, when attempting to attach to a channel, with a token that doesn't have the `subscribe` [capability](/docs/platform/auth/capabilities) for that channel, will cause that channel to enter the `FAILED` state.
 
 Whilst fatal errors won't get better on their own, they are fixable. For example, if a channel goes into the `FAILED` state due to the client not having the right capabilities to attach to it, that client could call [`authorize()`](/docs/api/realtime-sdk/authentication#authorize) to obtain a new token which does have the right capabilities, then call [`attach()`](/docs/api/realtime-sdk/channels#attach) on the channel. The library will not automatically reattach in the `FAILED` state, however explicit calls to [`attach()`](/docs/api/realtime-sdk/channels#attach) will make the client try again.
 
diff --git a/src/pages/docs/chat/authentication.mdx b/src/pages/docs/chat/authentication.mdx
new file mode 100644
index 0000000000..1e634ee63c
--- /dev/null
+++ b/src/pages/docs/chat/authentication.mdx
@@ -0,0 +1,114 @@
+---
+title: Chat authentication
+meta_description: "Configure authentication for Chat applications with the required capabilities."
+---
+
+For comprehensive authentication guidance including server implementation, client patterns, and token lifecycle, see [Platform Authentication](/docs/platform/auth/token).
+
+This page covers Chat-specific capabilities and room scoping.
+
+## Chat capabilities
+
+Your tokens need specific capabilities depending on which Chat features you use:
+
+| Feature | Required Capabilities |
+|---------|----------------------|
+| Send messages | `publish` |
+| Receive messages | `subscribe` |
+| Update messages | `message-update-any` or `message-update-own` |
+| Delete messages | `message-delete-any` or `message-delete-own` |
+| Message history | `subscribe`, `history` |
+| Message reactions | `annotation-publish`, optionally `annotation-subscribe` |
+| Presence | `subscribe`, `presence` |
+| Typing indicators | `publish`, `subscribe` |
+| Room reactions | `publish`, `subscribe` |
+| Occupancy | `subscribe`, `channel-metadata` |
+| **All Chat features** | `publish`, `subscribe`, `presence`, `history`, `channel-metadata`, `annotation-publish`, `annotation-subscribe`, `message-update-own`, `message-delete-own` |
+
+## Room-scoped capabilities
+
+You can restrict tokens to specific chat rooms. Chat rooms use a channel naming format of `your-room::$chat`:
+
+<Code>
+```javascript
+// Server-side JWT with room-scoped capabilities
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+const ablyJwt = jwt.sign(
+  {
+    'x-ably-capability': JSON.stringify({
+      // Only allow access to a specific room
+      'your-room::$chat': ['publish', 'subscribe', 'presence', 'history'],
+    }),
+    'x-ably-clientId': userId,
+  },
+  keySecret,
+  { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+);
+```
+
+```python
+# Server-side JWT with room-scoped capabilities
+import jwt
+import json
+import time
+import os
+
+key_name, key_secret = os.environ['ABLY_API_KEY'].split(':')
+
+now = int(time.time())
+ably_jwt = jwt.encode(
+    {
+        'iat': now,
+        'exp': now + 3600,
+        'x-ably-capability': json.dumps({
+            # Only allow access to a specific room
+            'your-room::$chat': ['publish', 'subscribe', 'presence', 'history'],
+        }),
+        'x-ably-clientId': user_id,
+    },
+    key_secret,
+    algorithm='HS256',
+    headers={'kid': key_name}
+)
+```
+</Code>
+
+<Aside data-type='important'>
+If you use API key authentication on the client, any user can claim any `clientId`, enabling impersonation. Always use [token authentication](/docs/platform/auth/token) in production.
+</Aside>
+
+## Client setup
+
+Use `authCallback` to fetch JWTs from your auth server:
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { ChatClient } from '@ably/chat';
+
+const realtimeClient = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token');
+      const jwt = await response.text();
+      callback(null, jwt);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
+
+const chatClient = new ChatClient(realtimeClient);
+```
+</Code>
+
+See [token authentication](/docs/platform/auth/token#auth-callback) for complete examples in all languages.
+
+## Further reading
+
+- [Token authentication](/docs/platform/auth/token) - Complete token authentication guide
+- [Capabilities](/docs/platform/auth/capabilities) - Fine-grained permission control
+- [Identified clients](/docs/platform/auth/identified-clients) - Assigning trusted client identities
diff --git a/src/pages/docs/chat/getting-started/android.mdx b/src/pages/docs/chat/getting-started/android.mdx
index f29424da58..bb5ebb1e8b 100644
--- a/src/pages/docs/chat/getting-started/android.mdx
+++ b/src/pages/docs/chat/getting-started/android.mdx
@@ -68,7 +68,11 @@ ably login
 
 Replace the contents of your `MainActivity.kt` file with the following code to set up the Ably client.
 
-Note that this is for example purposes only. In production, you should use [token authentication](/docs/auth/token) to avoid exposing your API keys publicly, the [`clientId`](/docs/auth/identified-clients) is used to identify the client:
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
+The [`clientId`](/docs/platform/auth/identified-clients) is used to identify the client:
 
 <Code>
 ```kotlin
@@ -106,9 +110,12 @@ class MainActivity : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
 
+        // WARNING: This uses an API key for simplicity.
+        // In production, use token authentication instead.
+        // See: https://ably.com/docs/platform/auth/token
         realtimeClient = AblyRealtime(
             ClientOptions().apply {
-                key = "{{API_KEY}}" // In production, you should use token authentication to avoid exposing your API keys publicly
+                key = "{{API_KEY}}"
                 clientId = "my-first-client"
             },
         )
@@ -968,7 +975,7 @@ class MainActivity : ComponentActivity() {
 
 Continue to explore the documentation with Kotlin as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Read more about using [rooms](/docs/chat/rooms?lang=kotlin) and sending [messages](/docs/chat/rooms/messages?lang=kotlin).
 * Find out more regarding [presence](/docs/chat/rooms/presence?lang=kotlin).
 * Read into pulling messages from [history](/docs/chat/rooms/history?lang=kotlin) and providing context to new joiners.
diff --git a/src/pages/docs/chat/getting-started/javascript.mdx b/src/pages/docs/chat/getting-started/javascript.mdx
index 17e0302680..a229492c05 100644
--- a/src/pages/docs/chat/getting-started/javascript.mdx
+++ b/src/pages/docs/chat/getting-started/javascript.mdx
@@ -84,7 +84,11 @@ ably login
 
 Clients establish a connection with Ably when they instantiate an SDK. This enables them to send and receive messages in realtime across channels.
 
-Create an `index.ts` file in your project and add the following function to instantiate a realtime client with the Pub/Sub SDK and then pass that client into the Chat SDK constructor. Provide an API key and a [`clientId`](/docs/auth/identified-clients) to identify the client. In production, use [token authentication](/docs/auth/token) so that your API keys are not exposed publicly.
+Create an `index.ts` file in your project and add the following function to instantiate a realtime client with the Pub/Sub SDK and then pass that client into the Chat SDK constructor. Provide an API key and a [`clientId`](/docs/platform/auth/identified-clients) to identify the client.
+
+<Aside data-type='note'>
+Using an API key directly is safe for server-side Node.js applications. If you're building a client-side application that runs in a browser or mobile app, use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
 
 <Code>
 ```javascript
@@ -98,6 +102,9 @@ async function getStarted() {
     throw new Error('ABLY_API_KEY environment variable is required');
   }
 
+  // Server-side: Using API key is safe here.
+  // For client-side browser/mobile apps, use token authentication instead.
+  // See: https://ably.com/docs/platform/auth/token
   const realtimeClient = new Ably.Realtime({ key: apiKey, clientId: 'my-first-client' });
 
   const chatClient = new ChatClient(realtimeClient);
@@ -297,7 +304,7 @@ setTimeout(() => realtimeClient.close(), 10000);
 
 Continue to explore the documentation with JavaScript as the selected language:
 
-* Understand [token authentication](/docs/auth/token?lang=javascript) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Read more about using [rooms](/docs/chat/rooms?lang=javascript) and sending [messages](/docs/chat/rooms/messages?lang=javascript).
 * Find out more regarding [presence](/docs/chat/rooms/presence?lang=javascript).
 * Read into pulling messages from [history](/docs/chat/rooms/history?lang=javascript) and providing context to new joiners.
diff --git a/src/pages/docs/chat/getting-started/jvm.mdx b/src/pages/docs/chat/getting-started/jvm.mdx
index cfc57bae24..dcf3a36083 100644
--- a/src/pages/docs/chat/getting-started/jvm.mdx
+++ b/src/pages/docs/chat/getting-started/jvm.mdx
@@ -83,7 +83,11 @@ Clients establish a connection with Ably when they instantiate an SDK. This enab
 
 Add the following code to the `App.kt` file created by `gradle init` set up the Ably client.
 
-Note that this is for example purposes only. In production, you should use [token authentication](/docs/auth/token) to avoid exposing your API keys publicly. The [`clientId`](/docs/auth/identified-clients) is used to identify the client when using an API key:
+<Aside data-type='note'>
+Using an API key directly is safe for server-side JVM applications. If you're building a client-side application (Android), use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
+
+The [`clientId`](/docs/platform/auth/identified-clients) is used to identify the client:
 
 <Code>
 ```kotlin
@@ -104,9 +108,11 @@ suspend fun main() {
 }
 
 suspend fun demonstrateMessages() {
+    // Server-side: Using API key is safe here.
+    // For Android apps, use token authentication instead.
+    // See: https://ably.com/docs/platform/auth/token
     val realtimeClient = AblyRealtime(
         ClientOptions().apply {
-            // In production, you should use token authentication to avoid exposing your API keys publicly
             key = ABLY_KEY
             clientId = "my-first-client"
         }
@@ -617,7 +623,7 @@ This demonstrates proper resource management and graceful shutdown of the chat c
 
 Continue to explore the documentation with Kotlin as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Read more about using [rooms](/docs/chat/rooms?lang=kotlin) and sending [messages](/docs/chat/rooms/messages?lang=kotlin).
 * Find out more regarding [presence](/docs/chat/rooms/presence?lang=kotlin).
 * Read into pulling messages from [history](/docs/chat/rooms/history?lang=kotlin) and providing context to new joiners.
diff --git a/src/pages/docs/chat/getting-started/react-native.mdx b/src/pages/docs/chat/getting-started/react-native.mdx
index f51daa7034..46ffbca6cc 100644
--- a/src/pages/docs/chat/getting-started/react-native.mdx
+++ b/src/pages/docs/chat/getting-started/react-native.mdx
@@ -75,7 +75,11 @@ ably login
 
 The Ably Pub/Sub SDK and the Ably Chat SDK expose React hooks and context providers to make it easier to use them in your React Native components. The [`AblyProvider`](/docs/getting-started/react-hooks#ably-provider) and [`ChatClientProvider`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatClientProvider.html) should be used at the top level of your application, typically in `App.tsx`. These are required when working with the [`useChatConnection`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useChatConnection.html) hook and [`ChatRoomProvider`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatRoomProvider.html) exposed by Ably Chat.
 
-In production, you should use [token authentication](/docs/auth/token) to avoid exposing your API keys publicly, the [`clientId`](/docs/auth/identified-clients) is used to identify the client.
+The [`clientId`](/docs/platform/auth/identified-clients) is used to identify the client.
+
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
 
 Replace the contents of your `App.tsx` file with the following code to set up the providers:
 
@@ -89,7 +93,9 @@ import { ChatClientProvider } from '@ably/chat/react';
 import { AblyProvider } from 'ably/react';
 import './global.css';
 
-// Create your Ably Realtime client and ChatClient instances:
+// WARNING: This uses an API key for simplicity.
+// In production, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 const realtimeClient = new Ably.Realtime({
   key: {{API_KEY}},
   clientId: 'my-first-client',
@@ -938,7 +944,7 @@ const handleDisconnect = () => {
 
 Continue to explore the documentation with React Native as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Read more about using [rooms](/docs/chat/rooms?lang=react) and sending [messages](/docs/chat/rooms/messages?lang=react).
 * Find out more regarding [presence](/docs/chat/rooms/presence?lang=react).
 * Read into pulling messages from [history](/docs/chat/rooms/history?lang=react) and providing context to new joiners.
diff --git a/src/pages/docs/chat/getting-started/react-ui-kit.mdx b/src/pages/docs/chat/getting-started/react-ui-kit.mdx
index cea08e6ee1..8eb825894d 100644
--- a/src/pages/docs/chat/getting-started/react-ui-kit.mdx
+++ b/src/pages/docs/chat/getting-started/react-ui-kit.mdx
@@ -107,6 +107,10 @@ ably-chat-react-ui-kit relies on the same React context providers as the underly
 
 In your main entry file (e.g. `main.tsx`), replace the content with the following code to set up the providers:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
   ```react
   // main.tsx
@@ -116,7 +120,9 @@ In your main entry file (e.g. `main.tsx`), replace the content with the followin
   import { ThemeProvider, AvatarProvider, ChatSettingsProvider } from '@ably/chat-react-ui-kit';
   import '@ably/chat-react-ui-kit/dist/style.css';
 
-  // Create Ably Realtime client
+  // WARNING: This uses an API key for simplicity.
+  // In production, use token authentication instead.
+  // See: https://ably.com/docs/platform/auth/token
   const ablyClient = new Ably.Realtime({
     key: process.env.ABLY_API_KEY,
     clientId: 'your-chat-client-id',
@@ -140,9 +146,7 @@ In your main entry file (e.g. `main.tsx`), replace the content with the followin
   ```
 </Code>
 
-The components you make throughout this guide will be wrapped in these providers to ensure they have access to the necessary context.
-
-In production, you should use [token authentication](/docs/auth/token) to avoid exposing your API keys publicly, the [`clientId`](/docs/auth/identified-clients) is used to identify the client.
+The components you make throughout this guide will be wrapped in these providers to ensure they have access to the necessary context. The [`clientId`](/docs/platform/auth/identified-clients) is used to identify the client.
 
 ### Provider responsibilities <a id="provider-responsibilities"/>
 
@@ -555,7 +559,7 @@ The UI Kit is experimental and highly likely to change in future releases.
 
 Continue to explore the documentation with React as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Read more about using [rooms](/docs/chat/rooms?lang=react) and sending [messages](/docs/chat/rooms/messages?lang=react).
 * Find out more regarding [presence](/docs/chat/rooms/presence?lang=react).
 * Read into pulling messages from [history](/docs/chat/rooms/history?lang=react) and providing context to new joiners.
diff --git a/src/pages/docs/chat/getting-started/react.mdx b/src/pages/docs/chat/getting-started/react.mdx
index 1be877d3b6..aca191935a 100644
--- a/src/pages/docs/chat/getting-started/react.mdx
+++ b/src/pages/docs/chat/getting-started/react.mdx
@@ -108,7 +108,11 @@ import {
 
 The Ably Pub/Sub SDK and the Ably Chat SDK expose React hooks and context providers to make it easier to use them in your React components. The [`AblyProvider`](/docs/getting-started/react-hooks#ably-provider) and [`ChatClientProvider`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatClientProvider.html) should be used at the top level of your application, typically in `main.tsx`. These are required when working with the [`useChatConnection`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useChatConnection.html) hook and [`ChatRoomProvider`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatRoomProvider.html) exposed by Ably Chat.
 
-In production, you should use [token authentication](/docs/auth/token) to avoid exposing your API keys publicly, the [`clientId`](/docs/auth/identified-clients) is used to identify the client.
+The [`clientId`](/docs/platform/auth/identified-clients) is used to identify the client.
+
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
 
 Replace the contents of your `src/main.tsx` file with the following code to set up the providers:
 
@@ -123,7 +127,9 @@ import { ChatClientProvider } from '@ably/chat/react';
 import { AblyProvider } from 'ably/react';
 import App from './App'; // Your main app component
 
-// Create your Ably Realtime client and ChatClient instances:
+// WARNING: This uses an API key for simplicity.
+// In production, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 const realtimeClient = new Ably.Realtime({
   key: import.meta.env.VITE_ABLY_API_KEY,
   clientId: 'my-first-client',
@@ -935,7 +941,7 @@ This will close the connection to Ably and clean up any associated resources.
 
 Continue to explore the documentation with React as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Read more about using [rooms](/docs/chat/rooms?lang=react) and sending [messages](/docs/chat/rooms/messages?lang=react).
 * Find out more regarding [presence](/docs/chat/rooms/presence?lang=react).
 * Read into pulling messages from [history](/docs/chat/rooms/history?lang=react) and providing context to new joiners.
diff --git a/src/pages/docs/chat/getting-started/swift.mdx b/src/pages/docs/chat/getting-started/swift.mdx
index 1725519f8e..8c6b993be0 100644
--- a/src/pages/docs/chat/getting-started/swift.mdx
+++ b/src/pages/docs/chat/getting-started/swift.mdx
@@ -60,9 +60,13 @@ Create a new iOS project with SwiftUI. For detailed instructions, refer to the [
 
 ## Step 1: Setting up Ably <a id="step-1"/>
 
-Replace the contents of your `ContentView.swift` file with the following code to set up the Ably client, this is using a demo API key, if you wish to use this application with the CLI, change the API key with your own key:
+Replace the contents of your `ContentView.swift` file with the following code to set up the Ably client.
 
-Note that this is for example purposes only. In production, you should use [token authentication](/docs/auth/token) to avoid exposing your API keys publicly, the [`clientId`](/docs/auth/identified-clients) is used to identify the client:
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
+The [`clientId`](/docs/platform/auth/identified-clients) is used to identify the client:
 
 <Code>
 ```swift
@@ -77,8 +81,11 @@ struct ContentView: View {
     @State private var chatClient: ChatClient
 
     init() {
+        // WARNING: This uses an API key for simplicity.
+        // In production, use token authentication instead.
+        // See: https://ably.com/docs/platform/auth/token
         let realtimeOptions = ARTClientOptions()
-        realtimeOptions.key = "{{API_KEY}}" // In production, use token authentication
+        realtimeOptions.key = "{{API_KEY}}"
         realtimeOptions.clientId = "my-first-client"
         let realtime = ARTRealtime(options: realtimeOptions)
 
@@ -1273,7 +1280,7 @@ var body: some View {
 
 Continue to explore the documentation with Swift as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Read more about using [rooms](/docs/chat/rooms?lang=swift) and sending [messages](/docs/chat/rooms/messages?lang=swift).
 * Find out more regarding [presence](/docs/chat/rooms/presence?lang=swift).
 * Read into pulling messages from [history](/docs/chat/rooms/history?lang=swift) and providing context to new joiners.
diff --git a/src/pages/docs/chat/index.mdx b/src/pages/docs/chat/index.mdx
index c4b96234fa..3f1bcf1d63 100644
--- a/src/pages/docs/chat/index.mdx
+++ b/src/pages/docs/chat/index.mdx
@@ -81,4 +81,4 @@ Take a look at a [livestream basketball game](https://ably-livestream-chat-demo.
 * Read more about using [rooms](/docs/chat/rooms) and sending [messages](/docs/chat/rooms/messages).
 * Read into pulling messages from [history](/docs/chat/rooms/history) and providing context to new joiners.
 * Learn about how to add [chat moderation](/docs/chat/moderation).
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [token authentication](/docs/platform/auth/token) before going to production.
diff --git a/src/pages/docs/chat/react-ui-kit/components.mdx b/src/pages/docs/chat/react-ui-kit/components.mdx
index b4fdce3818..7613cef773 100644
--- a/src/pages/docs/chat/react-ui-kit/components.mdx
+++ b/src/pages/docs/chat/react-ui-kit/components.mdx
@@ -136,6 +136,10 @@ The `App` component is a complete, ready-to-use chat application that combines a
 ### Usage
 
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```react
 import { App } from '@ably/chat-react-ui-kit';
diff --git a/src/pages/docs/chat/react-ui-kit/providers.mdx b/src/pages/docs/chat/react-ui-kit/providers.mdx
index 87519c7421..01ed91768d 100644
--- a/src/pages/docs/chat/react-ui-kit/providers.mdx
+++ b/src/pages/docs/chat/react-ui-kit/providers.mdx
@@ -12,6 +12,10 @@ The components in the Ably Chat React UI Kit rely on several React context provi
 
 Other providers like the `ChatSettingsProvider`, `ThemeProvider` and `AvatarProvider` can be used to manage themes, avatars, and chat settings respectively. These providers should be placed at the highest level of any component tree that contains Chat UI components.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```react
 import * as Ably from 'ably';
diff --git a/src/pages/docs/chat/react-ui-kit/setup.mdx b/src/pages/docs/chat/react-ui-kit/setup.mdx
index 8ffc7cfe97..95d79fbb17 100644
--- a/src/pages/docs/chat/react-ui-kit/setup.mdx
+++ b/src/pages/docs/chat/react-ui-kit/setup.mdx
@@ -49,6 +49,10 @@ The React UI Kit relies on several context providers to function properly. These
 
 Set up the required providers in your application's entry point:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```react
   import * as Ably from 'ably';
diff --git a/src/pages/docs/chat/rooms/index.mdx b/src/pages/docs/chat/rooms/index.mdx
index 4e8a3bdfc0..8e61b45fbd 100644
--- a/src/pages/docs/chat/rooms/index.mdx
+++ b/src/pages/docs/chat/rooms/index.mdx
@@ -36,6 +36,10 @@ All components that utilize chat feature hooks must be children of a `ChatRoomPr
 </If>
 
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```javascript
 const room = await chatClient.rooms.get('basketball-stream', {occupancy: {enableEvents: true}});
diff --git a/src/pages/docs/chat/setup.mdx b/src/pages/docs/chat/setup.mdx
index fdb0aafdaf..366eca79a3 100644
--- a/src/pages/docs/chat/setup.mdx
+++ b/src/pages/docs/chat/setup.mdx
@@ -11,19 +11,23 @@ If you have any feedback or feature requests, [let us know](https://forms.gle/Sm
 
 ## Authentication <a id="authentication"/>
 
-An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
-
 <Aside data-type='important'>
-The examples use basic authentication to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead, use token authentication.
+**Security requirement:** Client-side applications must use [JWT token authentication](/docs/platform/auth/token#choosing-jwt). Never expose your API key in client-side code.
 </Aside>
 
-[Sign up](https://ably.com/sign-up) to Ably to create an API key in the dashboard or use the [Control API](/docs/platform/account/control-api) to create an API key programmatically.
+Chat requires an authenticated client with a `clientId` to identify users. The recommended approach is:
+
+1. **Client-side apps** (browsers, iOS, Android): Use [JWT authentication](/docs/platform/auth/token#choosing-jwt) with `authCallback` to fetch JWTs from your server
+2. **Server-side apps** (Node.js, Python, etc.): Use your API key directly
 
-API keys and tokens have a set of [capabilities](/docs/auth/capabilities) assigned to them that specify which operations, such as subscribe or publish can be performed on which resources. To use the Chat SDK, the API key requires the following capabilities depending on which features are being used:
+[Sign up](https://ably.com/sign-up) to Ably to create an API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API key programmatically. Your server will use this key to issue tokens to clients.
+
+API keys and tokens have a set of [capabilities](/docs/platform/auth/capabilities) assigned to them that specify which operations, such as subscribe or publish can be performed on which resources. To use the Chat SDK, the API key requires the following capabilities depending on which features are being used:
 
 | Feature | Capabilities |
 | ------- | ------------ |
-| Send and receive messages | `publish`, `subscribe` |
+| Send messages | `publish` |
+| Receive messages | `subscribe` |
 | Update message | `message-update-any` or `message-update-own` |
 | Delete message | `message-delete-any` or `message-delete-own` |
 | Message history | `subscribe`, `history` |
@@ -39,7 +43,7 @@ When setting the capabilities for Chat, you can apply them to specific chat room
 * `dms:*` or
 * `*`
 
-For more guidance, see the [capabilities documentation](/docs/auth/capabilities).
+For more guidance, see the [capabilities documentation](/docs/platform/auth/capabilities).
 
 ## Install <a id="install"/>
 
@@ -82,7 +86,18 @@ Reference the Pub/Sub SDK and the Chat SDK within your HTML file:
 <script src="https://cdn.ably.com/lib/ably.min-2.js"></script>
 <script src="https://cdn.ably.com/lib/ably-chat.umd.cjs-0.js"></script>
 <script>
-  const realtime = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'});
+  // Client-side: Use token authentication (recommended)
+  const realtime = new Ably.Realtime({
+    authCallback: async (tokenParams, callback) => {
+      try {
+        const response = await fetch('/api/ably-token');
+        const token = await response.text();
+        callback(null, token);
+      } catch (error) {
+        callback(error, null);
+      }
+    },
+  });
   const chatClient = new AblyChat.ChatClient(realtime);
 </script>
 ```
@@ -143,18 +158,44 @@ Instantiate a realtime client using the Pub/Sub SDK and pass the generated clien
 Pass the `ChatClient` into the [`ChatClientProvider`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatClientProvider.html). The `ChatClient` instance will be available to all child components in your React component tree.
 </If>
 
+### Client-side authentication (recommended) <a id="client-side-auth"/>
+
+Use token authentication for browsers and mobile apps. Your auth server endpoint validates the user and returns an Ably token with the appropriate `clientId`:
+
 <Code>
 ```javascript
+// Client-side: Token authentication (recommended for browsers)
 import { LogLevel } from '@ably/chat'
 
-const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'});
+const realtimeClient = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token');
+      const token = await response.text();
+      callback(null, token);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
 const chatClient = new ChatClient(realtimeClient, { logLevel: LogLevel.Error });
 ```
 
 ```react
+// Client-side: Token authentication (recommended for React apps)
 import { LogLevel } from '@ably/chat'
 
-const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'});
+const realtimeClient = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token');
+      const token = await response.text();
+      callback(null, token);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
 const chatClient = new ChatClient(realtimeClient, { logLevel: LogLevel.Error });
 
 const App = () => {
@@ -167,22 +208,42 @@ const App = () => {
 ```
 
 ```swift
+// Client-side: Token authentication (recommended for iOS apps)
 let realtimeOptions = ARTClientOptions()
-realtimeOptions.key = "{{API_KEY}}"
-realtimeOptions.clientId = "<clientId>"
+realtimeOptions.authCallback = { tokenParams, callback in
+    // Fetch token from your auth server
+    fetchAblyToken { result in
+        switch result {
+        case .success(let tokenRequest):
+            callback(tokenRequest, nil)
+        case .failure(let error):
+            callback(nil, error)
+        }
+    }
+}
 let realtime = ARTRealtime(options: realtimeOptions)
 let chatClient = ChatClient(realtime: realtime)
 ```
 
 ```kotlin
+// Client-side: Token authentication (recommended for Android apps)
 import com.ably.chat.ChatClient
 import io.ably.lib.realtime.AblyRealtime
 import io.ably.lib.types.ClientOptions
 
 val realtimeClient = AblyRealtime(
     ClientOptions().apply {
-        key = "{{API_KEY}}"
-        clientId = "<clientId>"
+        authCallback = { tokenParams, callback ->
+            // Fetch token from your auth server
+            fetchAblyToken { result ->
+                result.onSuccess { tokenRequest ->
+                    callback.onSuccess(tokenRequest)
+                }
+                result.onFailure { error ->
+                    callback.onError(ErrorInfo(error.message, 40000, 401))
+                }
+            }
+        }
     },
 )
 
@@ -190,9 +251,118 @@ val chatClient = ChatClient(realtimeClient)
 ```
 </Code>
 
-A [`ClientOptions`](/docs/api/realtime-sdk#client-options) object may be passed to the Pub/Sub SDK instance to further customize the connection, however at a minimum you must set an API key and provide a `clientId` to ensure that the client is [identified](/docs/auth/identified-clients).
+Your auth server endpoint (`/api/ably-token`) should authenticate the user and return a token. See the [token authentication](/docs/platform/auth/token) documentation for server implementation examples.
+
+### Server-side authentication <a id="server-side-auth"/>
+
+For server-side applications or local development, you can use an API key directly:
+
+<Code>
+```javascript
+// Server-side only: API key authentication
+// WARNING: Never use this in client-side code (browsers, mobile apps)
+import { LogLevel } from '@ably/chat'
+
+const realtimeClient = new Ably.Realtime({
+  key: process.env.ABLY_API_KEY,
+  clientId: 'server-process-1',
+});
+const chatClient = new ChatClient(realtimeClient, { logLevel: LogLevel.Error });
+```
+</Code>
+
+<Aside data-type='important'>
+API key authentication should only be used server-side. For client-side apps (React, iOS, Android), always use [token authentication](#client-side-auth) instead.
+</Aside>
+
+A [`ClientOptions`](/docs/api/realtime-sdk#client-options) object may be passed to the Pub/Sub SDK instance to further customize the connection. When using token authentication, the `clientId` is set by your auth server. When using API key authentication server-side, you must provide a `clientId` to ensure that the client is [identified](/docs/platform/auth/identified-clients).
+
+### Using Ably JWT (alternative) <a id="jwt-auth"/>
+
+If you have existing JWT-based authentication infrastructure (Auth0, Firebase, Cognito, or custom), you can create Ably JWTs directly without using the Ably SDK on your server:
+
+**Server (no Ably SDK required):**
+
+<Code>
+```javascript
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+app.get('/api/ably-jwt', async (req, res) => {
+  // Your existing auth middleware validates the user
+  const userId = req.user.id;
+
+  const ablyJwt = jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({
+        '*': ['publish', 'subscribe', 'presence', 'history'],
+      }),
+      'x-ably-clientId': userId,
+    },
+    keySecret,
+    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+  );
+
+  res.send(ablyJwt);
+});
+```
+</Code>
+
+**Client:**
+
+<Code>
+```javascript
+const realtimeClient = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-jwt');
+      const jwt = await response.text();
+      callback(null, jwt);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
+const chatClient = new ChatClient(realtimeClient);
+```
+
+```swift
+let realtimeOptions = ARTClientOptions()
+realtimeOptions.authCallback = { tokenParams, callback in
+    fetchAblyJwt { result in
+        switch result {
+        case .success(let jwt):
+            callback(jwt as ARTTokenDetailsCompatible, nil)
+        case .failure(let error):
+            callback(nil, error)
+        }
+    }
+}
+let realtime = ARTRealtime(options: realtimeOptions)
+let chatClient = ChatClient(realtime: realtime)
+```
+
+```kotlin
+val realtimeClient = AblyRealtime(
+    ClientOptions().apply {
+        authCallback = Auth.TokenCallback { _ ->
+            // Fetch JWT from your server
+            fetchAblyJwt()
+        }
+    }
+)
+val chatClient = ChatClient(realtimeClient)
+```
+</Code>
+
+**Why choose JWT for Chat?**
+- No Ably SDK required on your server
+- Integrates with existing Auth0/Firebase/Cognito flows
+- Supports [channel-scoped claims](/docs/platform/auth/capabilities#custom-restrictions) for user roles in chat rooms
+- Eliminates client round-trip to Ably
 
-In many cases, a users unique application-specific identifier may be used as the `clientId` to provide consistent identification for clients across your application.
+See [Choosing a token mechanism](/docs/platform/auth/token#choosing) for detailed guidance on when to use JWT vs TokenRequest.
 
 Additional options can also be passed to the Chat client to customize the following properties:
 
@@ -229,7 +399,13 @@ Set the `logHandler` and `logLevel` properties when [instantiating a client](#in
 
 <Code>
 ```javascript
-const ably = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'});
+// Using token authentication (recommended for client-side)
+const ably = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    const response = await fetch('/api/ably-token');
+    callback(null, await response.text());
+  },
+});
 const chatClient = new ChatClient(ably, {logHandler: logWriteFunc, logLevel: 'debug' });
 ```
 
@@ -238,10 +414,16 @@ import * as Ably from 'ably';
 import { LogLevel } from '@ably/chat';
 import { ChatClientProvider } from '@ably/chat/react';
 
-const ably = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'});
+// Using token authentication (recommended for React apps)
+const ably = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    const response = await fetch('/api/ably-token');
+    callback(null, await response.text());
+  },
+});
 const chatClient = new ChatClient(ably, {logHandler: logWriteFunc, logLevel: 'debug' });
 
-const App = => {
+const App = () => {
   return (
     <ChatClientProvider client={chatClient}>
       <RestOfYourApp />
@@ -252,18 +434,30 @@ const App = => {
 
 ```swift
 let realtimeOptions = ARTClientOptions()
-realtimeOptions.key = "{{API_KEY}}"
-realtimeOptions.clientId = "<clientId>"
+// Using token authentication (recommended for iOS apps)
+realtimeOptions.authCallback = { tokenParams, callback in
+    fetchAblyToken { result in
+        switch result {
+        case .success(let tokenRequest): callback(tokenRequest, nil)
+        case .failure(let error): callback(nil, error)
+        }
+    }
+}
 let realtime = ARTRealtime(options: realtimeOptions)
 let clientOptions = ChatClientOptions(logHandler: SomeLogHandler(), logLevel: .debug)
 return ChatClient(realtime: realtime, clientOptions: clientOptions)
 ```
 
 ```kotlin
+// Using token authentication (recommended for Android apps)
 val realtimeClient = AblyRealtime(
     ClientOptions().apply {
-        key = "{{API_KEY}}"
-        clientId = "<clientId>"
+        authCallback = { tokenParams, callback ->
+            fetchAblyToken { result ->
+                result.onSuccess { callback.onSuccess(it) }
+                result.onFailure { callback.onError(ErrorInfo(it.message, 40000, 401)) }
+            }
+        }
     },
 )
 val chatClient = ChatClient(realtimeClient) {
diff --git a/src/pages/docs/connect/index.mdx b/src/pages/docs/connect/index.mdx
index 5e677d29ad..28ab5de5f0 100644
--- a/src/pages/docs/connect/index.mdx
+++ b/src/pages/docs/connect/index.mdx
@@ -10,6 +10,10 @@ redirect_from:
 
 Clients establish and maintain a connection to the Ably service using the most efficient transport available, typically [WebSockets](https://ably.com/topic/websockets).
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 ## Connection multiplexing <a id="multiplexing"/>
 
 Ably SDKs operate and multiplex all [channel](/docs/channels) traffic over a single connection. This means you can publish and subscribe to messages on any number of channels simultaneously using just one transport connection. This approach:
@@ -32,6 +36,10 @@ Ably SDKs open and maintain a connection to the Ably realtime servers on instant
 
 This example relies on the default auto-connect behavior of the SDK, checking for when the connection state is `connected` event:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
 // Using callbacks
@@ -137,7 +145,7 @@ Explicitly calling connect is unnecessary unless the ClientOptions attribute aut
 
 Connection monitoring allows you to view and manage the [states of connections](/docs/connect/states) to Ably, showing events for individual people connecting and disconnecting. The developer console in your Ably account also shows these events.
 
-This feature is intended for debugging, so once the number of new connections exceeds the number of messages per second permitted by the lifecycle channel, new events will be dropped. This means if you want a definitive list of everyone using your app you'd be best using [token authentication](/docs/auth/token) to create your own 'auth server'.
+This feature is intended for debugging, so once the number of new connections exceeds the number of messages per second permitted by the lifecycle channel, new events will be dropped. This means if you want a definitive list of everyone using your app you'd be best using [token authentication](/docs/platform/auth/token) to create your own 'auth server'.
 
 The Ably dashboard contains a developer console. In the developer console you can view connection events.
 
diff --git a/src/pages/docs/connect/states.mdx b/src/pages/docs/connect/states.mdx
index 60f98e8638..7d9c78e2f2 100644
--- a/src/pages/docs/connect/states.mdx
+++ b/src/pages/docs/connect/states.mdx
@@ -58,7 +58,7 @@ After a period of being offline a connection is re-established:
 
 The `Connection` object is an `EventEmitter` and emits an event whose name is the new state whenever there is a connection state change. An event listener function is passed a [ConnectionStateChange](/docs/api/realtime-sdk/connection#connection-state-change) object as the first argument for state change events.
 
-The `Connection` object can also emit an event that is not a state change: an `update` event. This happens when there's a change to connection conditions and there is no applicable status or the state doesn't change, such as when an SDK remains connected after a [reauth](/docs/auth).
+The `Connection` object can also emit an event that is not a state change: an `update` event. This happens when there's a change to connection conditions and there is no applicable status or the state doesn't change, such as when an SDK remains connected after a [reauth](/docs/platform/auth).
 
 <Code>
 ```realtime_javascript
diff --git a/src/pages/docs/faq/index.mdx b/src/pages/docs/faq/index.mdx
index b4a2057d32..27d26255b0 100644
--- a/src/pages/docs/faq/index.mdx
+++ b/src/pages/docs/faq/index.mdx
@@ -127,9 +127,9 @@ Available timeout options:
 
 ### Can I change my connection's clientId after connecting? <a id="client-id-change"/>
 
-A connection's [`clientId`](/docs/auth/identified-clients) is immutable once set.
+A connection's [`clientId`](/docs/platform/auth/identified-clients) is immutable once set.
 
-However, late initialization of `clientId` is possible. For instance, if the library is instantiated with an [`authCallback`](/docs/auth/token#auth-callback), the `clientId` may only be known after the callback completes. Similarly, if the library uses an opaque token string, it learns the `clientId` only after the server processes the token. In both cases, the "immutable" requirement is satisfied because the `clientId` is set during the client's first interaction with the server.
+However, late initialization of `clientId` is possible. For instance, if the library is instantiated with an [`authCallback`](/docs/platform/auth/token#auth-callback), the `clientId` may only be known after the callback completes. Similarly, if the library uses an opaque token string, it learns the `clientId` only after the server processes the token. In both cases, the "immutable" requirement is satisfied because the `clientId` is set during the client's first interaction with the server.
 
 ## Connection and network issues <a id="connection-network"/>
 
diff --git a/src/pages/docs/faq/push-faqs.mdx b/src/pages/docs/faq/push-faqs.mdx
index 2485ef1f46..938db7c0d1 100644
--- a/src/pages/docs/faq/push-faqs.mdx
+++ b/src/pages/docs/faq/push-faqs.mdx
@@ -69,7 +69,7 @@ Follow these steps to check if your device is correctly registered with Ably:
 
 | Step | Description | Action/State |
 |------|-------------|--------------|
-| Check registration | Go to Ably dashboard > Notifications > Device inspector. Search using `deviceId` or [`clientId`](/docs/auth/identified-clients). | - |
+| Check registration | Go to Ably dashboard > Notifications > Device inspector. Search using `deviceId` or [`clientId`](/docs/platform/auth/identified-clients). | - |
 | Device states | Registered and should receive notifications. Test using the push inspector in the Notifications tab or test using the `REST` `API` to publish directly to the `deviceId`. | **ACTIVE** |
 | Device states | Indicates an error "registration expired" if the app was uninstalled. | **FAILED** |
 | No registration Found | Enable verbose logs and retry the push registration process to view Ably push `API` requests. | - |
@@ -104,15 +104,15 @@ If there are no errors, the notification was successfully sent to the push provi
 
 ### Why are my push notifications duplicated? <a id="duplicated-notifications"/>
 
-Consistent duplication on a specific device usually indicates both a `deviceId` and a [`clientId`](/docs/auth/identified-clients) subscription to the push [channel](/docs/channels). Remove one to prevent duplication.
+Consistent duplication on a specific device usually indicates both a `deviceId` and a [`clientId`](/docs/platform/auth/identified-clients) subscription to the push [channel](/docs/channels). Remove one to prevent duplication.
 
 - DeviceId subscriptions: Deliver to a single device.
-- [ClientId subscriptions](/docs/auth/identified-clients): Deliver to all devices identified by that `clientId`.
+- [ClientId subscriptions](/docs/platform/auth/identified-clients): Deliver to all devices identified by that `clientId`.
 
 ### Why can I not publish push notifications on channels? <a id="cannot-publish-push"/>
 
 If you're unable to [publish](/docs/channels#publish) push notifications to [channels](/docs/channels), this is typically due to configuration or permission issues. The following are possible reasons for this issue:
 
 1. [Channel Rules](/docs/general/channel-rules): Channels must be explicitly enabled for push notifications via channel rules. They are disabled by default.
-2. [Permissions](/docs/auth/capabilities): The publisher must have permission to publish to that channel.
+2. [Permissions](/docs/platform/auth/capabilities): The publisher must have permission to publish to that channel.
 3. Invalid Payload: If the push notification payload in the `extras` field is invalid, the message may be rejected immediately.
diff --git a/src/pages/docs/getting-started/dotnet.mdx b/src/pages/docs/getting-started/dotnet.mdx
index c235dd4ec1..afa5a2677a 100644
--- a/src/pages/docs/getting-started/dotnet.mdx
+++ b/src/pages/docs/getting-started/dotnet.mdx
@@ -14,7 +14,7 @@ You'll establish a realtime connection to Ably and learn to publish and subscrib
 
 1. [Sign up](https://ably.com/sign-up) for an Ably account.
 2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
-3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/auth/capabilities).
+3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/platform/auth/capabilities).
 4. Install [.NET SDK](https://dotnet.microsoft.com/download) (version 6.0 or later).
 5. Create a new C# console application:
 
@@ -65,7 +65,11 @@ Clients establish a connection with Ably when they instantiate an SDK instance.
 
 Open up the [dev console](https://ably.com/accounts/any/apps/any/console) of your first app before instantiating your client so that you can see what happens.
 
-Replace the contents of your `Program.cs` file with functionality to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Replace the contents of your `Program.cs` file with functionality to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='note'>
+Using an API key directly is safe for server-side .NET applications. If you're building a client-side application (Blazor WebAssembly, MAUI, etc.), use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
 
 <Code>
 ```csharp
@@ -77,7 +81,9 @@ class Program
 {
     static async Task Main(string[] args)
     {
-        // Initialize the Ably Realtime client
+        // Server-side: Using API key is safe here.
+        // For client-side apps, use token authentication instead.
+        // See: https://ably.com/docs/platform/auth/token
         var clientOptions = new ClientOptions("{{API_KEY}}")
         {
             ClientId = "my-first-client"
@@ -232,7 +238,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with C# .NET as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=csharp).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=csharp) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/flutter.mdx b/src/pages/docs/getting-started/flutter.mdx
index c3c4a5ccf3..4bf5ec5e75 100644
--- a/src/pages/docs/getting-started/flutter.mdx
+++ b/src/pages/docs/getting-started/flutter.mdx
@@ -16,7 +16,7 @@ You'll establish a realtime connection to Ably and learn to publish and subscrib
 
 1. [Sign up](https://ably.com/sign-up) for a free Ably account.
 2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
-3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/auth/capabilities).
+3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/platform/auth/capabilities).
 
 ### Create a Flutter project <a id="prerequisites-create-project"/>
 
@@ -54,6 +54,10 @@ flutter pub get
 
 Create a new file `lib/ably_service.dart` to manage your Ably connection:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```flutter
 // lib/ably_service.dart
@@ -70,6 +74,9 @@ class AblyService {
   AblyService._internal();
 
   Future<void> init() async {
+    // WARNING: This uses an API key for simplicity.
+    // In production, use token authentication instead.
+    // See: https://ably.com/docs/platform/auth/token
     final clientOptions = ably.ClientOptions(
       key: '{{API_KEY}}',
       clientId: 'my-first-client',
@@ -189,7 +196,11 @@ ably login
 
 Clients establish a connection with Ably when they instantiate an SDK instance. This enables them to send and receive messages in realtime across channels.
 
-In the [Set up Ably Realtime Client](#prerequisites-setup-ably-client) section, you added code to create an Ably Realtime client. This code creates a new Realtime client instance, establishing a connection to Ably when your application starts. At the minimum you need to provide an authentication mechanism. While using an API key is fine for the purposes of this guide, you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+In the [Set up Ably Realtime Client](#prerequisites-setup-ably-client) section, you added code to create an Ably Realtime client. This code creates a new Realtime client instance, establishing a connection to Ably when your application starts. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='important'>
+While using an API key is fine for this guide, you should never embed your API key in a mobile app in production. Use [token authentication](/docs/platform/auth/token) in production to keep your API key secure on your server.
+</Aside>
 
 To monitor the Ably connection state within your application, create a widget that displays the current connection state. Create a new file `lib/widgets/connection_state.dart`:
 
@@ -728,7 +739,7 @@ Message number 5
 
 Continue to explore the documentation with Flutter as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=flutter).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=flutter) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/go.mdx b/src/pages/docs/getting-started/go.mdx
index 092eeb208d..57e9406ed4 100644
--- a/src/pages/docs/getting-started/go.mdx
+++ b/src/pages/docs/getting-started/go.mdx
@@ -56,7 +56,11 @@ ably login
 
 Clients establish a connection with Ably when they instantiate an SDK instance. This enables them to send and receive messages in realtime across channels.
 
-Create a `main.go` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Create a `main.go` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='note'>
+Using an API key directly is safe for server-side Go applications. If you're building a client-side application, use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
 
 <Code>
 ```go
@@ -71,6 +75,9 @@ import (
 )
 
 func main() {
+	// Server-side: Using API key is safe here.
+	// For client-side apps, use token authentication instead.
+	// See: https://ably.com/docs/platform/auth/token
 	client, err := ably.NewRealtime(
 		ably.WithKey("{{API_KEY}}"),
 		ably.WithClientID("my-first-client"),
@@ -243,7 +250,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with Go as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=go).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=go) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/java.mdx b/src/pages/docs/getting-started/java.mdx
index c5cc497dff..186c433090 100644
--- a/src/pages/docs/getting-started/java.mdx
+++ b/src/pages/docs/getting-started/java.mdx
@@ -14,7 +14,7 @@ You'll establish a realtime connection to Ably and learn to publish and subscrib
 
 1. [Sign up](https://ably.com/sign-up) for an Ably account.
 2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
-3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/auth/capabilities).
+3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/platform/auth/capabilities).
 4. Install [Java Development Kit (JDK)](https://adoptium.net/) version 8 or greater.
 5. Create a new project and add the Ably [Pub/Sub Java SDK](https://github.com/ably/ably-java) as a dependency.
 
@@ -76,7 +76,11 @@ Clients establish a connection with Ably when they instantiate an SDK instance.
 
 Open up the [dev console](https://ably.com/accounts/any/apps/any/console) of your first app before instantiating your client so that you can see what happens.
 
-Replace the contents of your `App.java` file with functionality to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Replace the contents of your `App.java` file with functionality to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='note'>
+Using an API key directly is safe for server-side Java applications. If you're building a client-side application (Android), use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
 
 <Code>
 ```java
@@ -94,7 +98,9 @@ import io.ably.lib.types.PaginatedResult;
 public class App {
     public static void main(String[] args) {
         try {
-            // Initialize the Ably Realtime client
+            // Server-side: Using API key is safe here.
+            // For Android apps, use token authentication instead.
+            // See: https://ably.com/docs/platform/auth/token
             ClientOptions options = new ClientOptions("{{API_KEY}}");
             options.clientId = "my-first-client";
             AblyRealtime realtime = new AblyRealtime(options);
@@ -239,7 +245,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with Java as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=java).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=java) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/javascript.mdx b/src/pages/docs/getting-started/javascript.mdx
index 4cfeab0d33..0d4067e60b 100644
--- a/src/pages/docs/getting-started/javascript.mdx
+++ b/src/pages/docs/getting-started/javascript.mdx
@@ -50,7 +50,11 @@ Clients establish a connection with Ably when they instantiate an SDK instance.
 
 Open up the [dev console](https://ably.com/accounts/any/apps/any/console) of your first app before instantiating your client so that you can see what happens.
 
-Create an `index.html` file in your project and add the following HTML to include the Ably JavaScript SDK via CDN and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token#jwt) in a production app. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Create an `index.html` file in your project and add the following HTML to include the Ably JavaScript SDK via CDN and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
 
 <Code>
 ```html
@@ -75,6 +79,9 @@ Create an `index.html` file in your project and add the following HTML to includ
         }
 
         async function getStarted() {
+            // WARNING: This uses an API key for simplicity.
+            // In production, use token authentication instead.
+            // See: https://ably.com/docs/platform/auth/token
             const realtimeClient = new Ably.Realtime({
                 key: '{{API_KEY}}',
                 clientId: 'my-first-client'
@@ -206,7 +213,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with JavaScript as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=javascript).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=javascript) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/kotlin.mdx b/src/pages/docs/getting-started/kotlin.mdx
index d9e5df9b0a..551d6b0859 100644
--- a/src/pages/docs/getting-started/kotlin.mdx
+++ b/src/pages/docs/getting-started/kotlin.mdx
@@ -55,7 +55,11 @@ Clients establish a connection with Ably when they instantiate an SDK. This enab
 
 Open up the [dev console](https://ably.com/accounts/any/apps/any/console) of your first app before instantiating your client so that you can see what happens.
 
-Create a `Main.kt` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Create a `Main.kt` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
 
 <Code>
 ```kotlin
@@ -64,6 +68,9 @@ import io.ably.lib.realtime.ConnectionEvent
 import io.ably.lib.types.ClientOptions
 
 fun getStarted() {
+  // WARNING: This uses an API key for simplicity.
+  // In production, use token authentication instead.
+  // See: https://ably.com/docs/platform/auth/token
   val realtimeClient = AblyRealtime(ClientOptions().apply {
     key = "{{API_KEY}}"
     clientId = "my-first-client"
@@ -184,7 +191,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with Kotlin as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=kotlin).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=kotlin) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/laravel.mdx b/src/pages/docs/getting-started/laravel.mdx
index 42667c2ba3..267bbefaf7 100644
--- a/src/pages/docs/getting-started/laravel.mdx
+++ b/src/pages/docs/getting-started/laravel.mdx
@@ -218,6 +218,10 @@ npm install @ably/laravel-echo ably axios
 
 Create or update `resources/js/bootstrap.js` to include Echo configuration:
 
+<Aside data-type='note'>
+This example uses an API key for simplicity. Laravel Echo handles authentication through token-based authentication automatically. In production, you should configure Laravel's [broadcasting authentication](https://laravel.com/docs/broadcasting#authorizing-channels) for private and presence channels. For public channels shown here, the API key is exposed to the client but scoped by the broadcaster configuration.
+</Aside>
+
 <Code fixed="true">
 ```laravel
 import axios from 'axios';
@@ -226,6 +230,8 @@ window.axios = axios;
 window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
 
 // Configure Laravel Echo with Ably
+// Note: For production, configure proper channel authorization
+// See: https://ably.com/docs/platform/auth/token
 import Echo from '@ably/laravel-echo';
 import * as Ably from 'ably';
 
diff --git a/src/pages/docs/getting-started/node.mdx b/src/pages/docs/getting-started/node.mdx
index 3fdcc7b452..87b661109f 100644
--- a/src/pages/docs/getting-started/node.mdx
+++ b/src/pages/docs/getting-started/node.mdx
@@ -68,13 +68,20 @@ Clients establish a connection with Ably when they instantiate an SDK instance.
 
 Open up the [dev console](https://ably.com/accounts/any/apps/any/console) of your first app before instantiating your client so that you can see what happens.
 
-Create an `index.js` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token#jwt) in a production app. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Create an `index.js` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='note'>
+Using an API key directly is safe for server-side Node.js applications. If you're building a client-side application that runs in a browser, use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
 
 <Code>
 ```nodejs
 import * as Ably from 'ably';
 
 async function getStarted() {
+  // Server-side: Using API key is safe here.
+  // For client-side browser apps, use token authentication instead.
+  // See: https://ably.com/docs/platform/auth/token
   const realtimeClient = new Ably.Realtime({
     key: process.env.ABLY_API_KEY,
     clientId: 'my-first-client'
@@ -199,7 +206,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with JavaScript as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=nodejs).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=nodejs) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/objective-c.mdx b/src/pages/docs/getting-started/objective-c.mdx
index d1d3f41d19..1b6076bb4f 100644
--- a/src/pages/docs/getting-started/objective-c.mdx
+++ b/src/pages/docs/getting-started/objective-c.mdx
@@ -18,7 +18,7 @@ You'll establish a realtime connection to Ably and learn to publish and subscrib
 
 1. [Sign up](https://ably.com/sign-up) for an Ably account.
 2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
-3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/auth/capabilities).
+3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/platform/auth/capabilities).
 4. Install Xcode and create a new Objective-C project.
 5. Add the Ably [Pub/Sub Objective-C SDK](https://github.com/ably/ably-cocoa) as a dependency.
 
@@ -70,7 +70,11 @@ Clients establish a connection with Ably when they instantiate an SDK instance.
 
 Open up the [dev console](https://ably.com/accounts/any/apps/any/console) of your first app before instantiating your client so that you can see what happens.
 
-Replace the contents of your `main.m` file with functionality to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Replace the contents of your `main.m` file with functionality to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
 
 <Code>
 ```objc
@@ -79,7 +83,9 @@ Replace the contents of your `main.m` file with functionality to instantiate the
 
 int main(int argc, const char * argv[]) {
     @autoreleasepool {
-        // Initialize the Ably Realtime client
+        // WARNING: This uses an API key for simplicity.
+        // In production, use token authentication instead.
+        // See: https://ably.com/docs/platform/auth/token
         ARTClientOptions *options = [[ARTClientOptions alloc] initWithKey:@"{{API_KEY}}"];
         options.clientId = @"my-first-client";
         ARTRealtime *realtime = [[ARTRealtime alloc] initWithOptions:options];
@@ -227,7 +233,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with Objective-C as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=objc).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=objc) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/php.mdx b/src/pages/docs/getting-started/php.mdx
index 8e2a34b92d..db7fdd0e8e 100644
--- a/src/pages/docs/getting-started/php.mdx
+++ b/src/pages/docs/getting-started/php.mdx
@@ -66,7 +66,7 @@ ably login
 
 Clients can make REST API requests to Ably when they instantiate a REST SDK instance. This enables them to publish messages to channels and retrieve channel information.
 
-Create a `get_started.php` file in your project and add the following code to instantiate the SDK and make requests to Ably. At the minimum you need to provide an authentication mechanism. Using an API key directly is fine for server-side environments like PHP where the key remains secure. However, for frontend clients, you should use [token authentication](/docs/auth/token) instead of exposing API keys. In this example, the [`clientId`](/docs/auth/identified-clients) will be the name of the client sending the message:
+Create a `get_started.php` file in your project and add the following code to instantiate the SDK and make requests to Ably. At the minimum you need to provide an authentication mechanism. Using an API key directly is fine for server-side environments like PHP where the key remains secure. However, for frontend clients, you should use [token authentication](/docs/platform/auth/token) instead of exposing API keys. In this example, the [`clientId`](/docs/platform/auth/identified-clients) will be the name of the client sending the message:
 
 <Code>
 ```php
@@ -76,6 +76,9 @@ require 'vendor/autoload.php';
 
 use Ably\AblyRest;
 
+// Server-side: Using API key is safe here.
+// For frontend clients, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 $ably = new AblyRest(['key' => '{{API_KEY}}', 'clientId' => 'my-first-client']);
 ```
 </Code>
@@ -230,7 +233,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with PHP as the selected language:
 
-* Dive into [authenticating](/docs/auth/token#jwt?lang=php) your frontend applications with your PHP backend.
+* Dive into [authenticating](/docs/platform/auth/token#jwt?lang=php) your frontend applications with your PHP backend.
 * Explore more [advanced](/docs/pub-sub/advanced?lang=php) Pub/Sub concepts.
 
 You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/api/rest-sdk?lang=php).
diff --git a/src/pages/docs/getting-started/python.mdx b/src/pages/docs/getting-started/python.mdx
index 85e63129eb..4ca8b4943b 100644
--- a/src/pages/docs/getting-started/python.mdx
+++ b/src/pages/docs/getting-started/python.mdx
@@ -63,7 +63,11 @@ ably login
 
 Clients establish a connection with Ably when they instantiate an SDK instance. This enables them to send and receive messages in realtime across channels.
 
-Create a `get_started.py` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token) in production environments. A [`client_id`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Create a `get_started.py` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`client_id`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='note'>
+Using an API key directly is safe for server-side Python applications. If you're building a client-side application, use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
 
 <Code>
 ```python
@@ -71,7 +75,9 @@ import asyncio
 from ably import AblyRealtime
 
 async def get_started():
-    # Initialize the Ably Realtime client
+    # Server-side: Using API key is safe here.
+    # For client-side apps, use token authentication instead.
+    # See: https://ably.com/docs/platform/auth/token
     async with AblyRealtime("{{API_KEY}}", client_id="my-first-client") as ably_realtime:
         def on_state_change(state_change):
             if state_change.current.value == "connected":
@@ -198,7 +204,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with Python as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=python).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=python) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/react-hooks.mdx b/src/pages/docs/getting-started/react-hooks.mdx
index e748fa91e9..2282336d4d 100644
--- a/src/pages/docs/getting-started/react-hooks.mdx
+++ b/src/pages/docs/getting-started/react-hooks.mdx
@@ -40,12 +40,12 @@ React version 16.8 or above is required.
 
 ## Authenticate <a id="authenticate"/>
 
-An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
+An [API key](/docs/platform/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/platform/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/platform/auth/token).
 
 [Sign up](https://ably.com/sign-up) to Ably to create an API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API programmatically.
 
 <Aside data-type='important'>
-The examples use [basic authentication](/docs/auth/basic) to demonstrate usage for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication.](/docs/auth/token)
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
 </Aside>
 
 ## Usage <a id="usage"/>
diff --git a/src/pages/docs/getting-started/react-native.mdx b/src/pages/docs/getting-started/react-native.mdx
index bc49ab67c2..006edbd7b9 100644
--- a/src/pages/docs/getting-started/react-native.mdx
+++ b/src/pages/docs/getting-started/react-native.mdx
@@ -16,7 +16,7 @@ You'll establish a realtime connection to Ably and learn to publish and subscrib
 
 1. [Sign up](https://ably.com/sign-up) for a free Ably account.
 2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
-3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/auth/capabilities).
+3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/platform/auth/capabilities).
 
 ### Create a React Native project <a id="prerequisites-create-project"/>
 
@@ -95,6 +95,10 @@ The `AblyProvider` is required when using the `useAbly()` and `useConnectionStat
 
 Replace the contents of your `App.tsx` file with the following code to set up the `AblyProvider`:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```react
 // App.tsx
@@ -106,7 +110,9 @@ import { SafeAreaView, Text, View } from 'react-native';
 
 import './global.css';
 
-// Create your Ably Realtime client
+// WARNING: This uses an API key for simplicity.
+// In production, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 const realtimeClient = new Ably.Realtime({
   key: process.env.ABLY_API_KEY,
   clientId: 'my-first-client',
@@ -175,6 +181,9 @@ In the [Set up AblyProvider](#prerequisites-setup-ably-provider) section, you ad
 
 <Code>
 ```react
+// WARNING: This uses an API key for simplicity.
+// In production, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 const realtimeClient = new Ably.Realtime({
   key: process.env.ABLY_API_KEY,
   clientId: 'my-first-client',
@@ -182,7 +191,11 @@ const realtimeClient = new Ably.Realtime({
 ```
 </Code>
 
-This code creates a new Realtime client instance, establishing a connection to Ably when your application starts. At the minimum you need to provide an authentication mechanism. While using an API key is fine for the purposes of this guide, you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+This code creates a new Realtime client instance, establishing a connection to Ably when your application starts. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='important'>
+While using an API key is fine for this guide, you should never embed your API key in a mobile app in production. Use [token authentication](/docs/platform/auth/token) in production to keep your API key secure on your server.
+</Aside>
 
 To monitor the Ably connection state within your application, create a component that uses the `useConnectionStateListener()` hook provided by the Ably Pub/Sub SDK. This hook must be nested inside an `AblyProvider`, so the component must be placed within the `AblyProvider` in your application.
 
@@ -682,7 +695,7 @@ Message number 5
 
 Continue to explore the documentation with React as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=react).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=react) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/react.mdx b/src/pages/docs/getting-started/react.mdx
index 5b465a54be..df4b602450 100644
--- a/src/pages/docs/getting-started/react.mdx
+++ b/src/pages/docs/getting-started/react.mdx
@@ -115,6 +115,10 @@ The `AblyProvider` is required when using the `useAbly()` and `useConnectionStat
 
 Replace the contents of your `src/main.tsx` file with the following code to set up the `AblyProvider`:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```react
 // src/main.tsx
@@ -125,7 +129,9 @@ import { createRoot } from 'react-dom/client';
 import App from './App.tsx';
 import './index.css';
 
-// Create your Ably Realtime client
+// WARNING: This uses an API key for simplicity.
+// In production, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 const realtimeClient = new Ably.Realtime({
   key: '{{API_KEY}}',
   clientId: 'my-first-client',
@@ -181,6 +187,9 @@ In the [Set up AblyProvider](#prerequisites-setup-ably-provider) section, you ad
 
 <Code>
 ```react
+// WARNING: This uses an API key for simplicity.
+// In production, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 const realtimeClient = new Ably.Realtime({
   key: '{{API_KEY}}',
   clientId: 'my-first-client',
@@ -188,7 +197,11 @@ const realtimeClient = new Ably.Realtime({
 ```
 </Code>
 
-This code creates a new Realtime client instance, establishing a connection to Ably when your application starts. At the minimum you need to provide an authentication mechanism. While using an API key is fine for the purposes of this guide, you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+This code creates a new Realtime client instance, establishing a connection to Ably when your application starts. At the minimum you need to provide an authentication mechanism. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='important'>
+While using an API key is fine for this guide, you should never expose your API key in client-side code in production. Use [token authentication](/docs/platform/auth/token) in production to keep your API key secure on your server.
+</Aside>
 
 To monitor the Ably connection state within your application, create a component that uses the `useConnectionStateListener()` hook provided by the Ably Pub/Sub SDK. This hook must be nested inside an `AblyProvider`, so the component must be placed within the `AblyProvider` in your application.
 
@@ -627,7 +640,7 @@ Message number 5
 
 Continue to explore the documentation with React as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=react).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=react) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/ruby.mdx b/src/pages/docs/getting-started/ruby.mdx
index 608c0a72b4..8c0b220cdc 100644
--- a/src/pages/docs/getting-started/ruby.mdx
+++ b/src/pages/docs/getting-started/ruby.mdx
@@ -14,7 +14,7 @@ You'll establish a realtime connection to Ably and learn to publish and subscrib
 
 1. [Sign up](https://ably.com/sign-up) for an Ably account.
 2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
-3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/auth/capabilities).
+3. Your API key will need the `publish`, `subscribe`, `presence` and `history` [capabilities](/docs/platform/auth/capabilities).
 4. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) version 2.7 or greater.
 5. Create a new project and install the Ably [Pub/Sub Ruby SDK](https://github.com/ably/ably-ruby):
 
@@ -63,7 +63,11 @@ Clients establish a connection with Ably when they instantiate an SDK instance.
 
 Open up the [dev console](https://ably.com/accounts/any/apps/any/console) of your first app before instantiating your client so that you can see what happens.
 
-Create a `get_started.rb` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use [token authentication](/docs/auth/token) in production environments. A [`client_id`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence:
+Create a `get_started.rb` file in your project and add the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. A [`client_id`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='note'>
+Using an API key directly is safe for server-side Ruby applications. If you're building a client-side application, use [token authentication](/docs/platform/auth/token) instead to keep your API key secure.
+</Aside>
 
 <Code>
 ```ruby
@@ -72,7 +76,9 @@ require 'eventmachine'
 
 def get_started
   EventMachine.run do
-    # Initialize the Ably Realtime client
+    # Server-side: Using API key is safe here.
+    # For client-side apps, use token authentication instead.
+    # See: https://ably.com/docs/platform/auth/token
     realtime_client = Ably::Realtime.new(key: '{{API_KEY}}', client_id: 'my-first-client')
 
     # Wait for the connection to be established
@@ -201,7 +207,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with Ruby as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=ruby).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=ruby) Pub/Sub concepts.
 
diff --git a/src/pages/docs/getting-started/swift.mdx b/src/pages/docs/getting-started/swift.mdx
index 2b33c2d6e3..9228542432 100644
--- a/src/pages/docs/getting-started/swift.mdx
+++ b/src/pages/docs/getting-started/swift.mdx
@@ -69,12 +69,19 @@ import Ably
 ```
 </Code>
 
-Create an instance of `ARTRealtime` with your API key and provide a `clientId`. While using an API key is fine for the purposes of this guide, you should use [token authentication](/docs/auth/token) in production environments. A [`clientId`](/docs/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+Create an instance of `ARTRealtime` with your API key and provide a `clientId`. A [`clientId`](/docs/platform/auth/identified-clients) ensures the client is identified, which is required to use certain features, such as presence.
+
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
 
 This `ARTRealtime` instance is the main entry point for the realtime library. The `ARTRealtime` client connects to Ably as soon as it's instantiated, using a basic transport such as a raw TCP socket or a WebSocket:
 
 <Code>
 ```swift
+// WARNING: This uses an API key for simplicity.
+// In production, use token authentication instead.
+// See: https://ably.com/docs/platform/auth/token
 let clientOptions = ARTClientOptions(key: "{{API_KEY}}")
 clientOptions.clientId = "my-first-client"
 let realtime = ARTRealtime(options: clientOptions)
@@ -246,7 +253,7 @@ The output will look similar to the following:
 
 Continue to explore the documentation with Swift as the selected language:
 
-* Understand [token authentication](/docs/auth/token) before going to production.
+* Understand [JWT token authentication](/docs/platform/auth/token#choosing-jwt) before going to production.
 * Understand how to effectively [manage connections](https://ably.com/docs/connect#close?lang=ruby).
 * Explore more [advanced](/docs/pub-sub/advanced?lang=ruby) Pub/Sub concepts.
 
diff --git a/src/pages/docs/guides/chat/build-livestream.mdx b/src/pages/docs/guides/chat/build-livestream.mdx
index 72300d6d59..9cd6dc6b4e 100644
--- a/src/pages/docs/guides/chat/build-livestream.mdx
+++ b/src/pages/docs/guides/chat/build-livestream.mdx
@@ -371,5 +371,5 @@ Before you go live, review these key points:
 * Try out the [livestream chat demo](https://ably-livestream-chat-demo.vercel.app).
 * Read the [JavaScript / TypeScript](/docs/chat/getting-started/javascript) or [React](/docs/chat/getting-started/react) getting started guides.
 * Learn about how to add [chat moderation](/docs/chat/moderation).
-* Understand [token authentication](/docs/auth/token#jwt) before going to production.
+* Understand [token authentication](/docs/platform/auth/token#jwt) before going to production.
 * Learn how to set up [server-side batching](/docs/messages/batch#server-side).
diff --git a/src/pages/docs/liveobjects/concepts/operations.mdx b/src/pages/docs/liveobjects/concepts/operations.mdx
index 3353bfa619..7ca640bf0b 100644
--- a/src/pages/docs/liveobjects/concepts/operations.mdx
+++ b/src/pages/docs/liveobjects/concepts/operations.mdx
@@ -271,6 +271,10 @@ myCounter.increment(1);
 
 In the [REST API](/docs/liveobjects/rest-api-usage#updating-objects-by-id), the relationship between operations and object IDs is made explicit:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```shell
 curl -X POST https://main.realtime.ably.net/channels/my-channel/objects \
@@ -307,7 +311,7 @@ The following are the properties of an `ObjectMessage`:
 | Property | Description |
 |----------|-------------|
 | **id** | Unique ID assigned by Ably to this object message |
-| **clientId** | The [ID of the client](/docs/auth/identified-clients) that published this operation |
+| **clientId** | The [ID of the client](/docs/platform/auth/identified-clients) that published this operation |
 | **connectionId** | The ID of the connection used to publish this operation |
 | **timestamp** | The timestamp of when the object message was received by Ably, as milliseconds since the Unix epoch |
 | **channel** | The name of the channel the object message was published to |
diff --git a/src/pages/docs/liveobjects/inband-objects.mdx b/src/pages/docs/liveobjects/inband-objects.mdx
index ca30536478..d5416e880e 100644
--- a/src/pages/docs/liveobjects/inband-objects.mdx
+++ b/src/pages/docs/liveobjects/inband-objects.mdx
@@ -53,7 +53,7 @@ await channel.setOptions({ params: { objects: 'objects' } });
 </Code>
 
 <Aside data-type='important'>
-Clients require the `channel-metadata` [capability](/docs/auth/capabilities) to receive inband objects updates.
+Clients require the `channel-metadata` [capability](/docs/platform/auth/capabilities) to receive inband objects updates.
 </Aside>
 
 ## Subscribe to updates <a id="inband-objects-subscribe"/>
diff --git a/src/pages/docs/liveobjects/quickstart/java.mdx b/src/pages/docs/liveobjects/quickstart/java.mdx
index 3594c5336a..9c004c0216 100644
--- a/src/pages/docs/liveobjects/quickstart/java.mdx
+++ b/src/pages/docs/liveobjects/quickstart/java.mdx
@@ -20,22 +20,22 @@ You will learn how to:
 
 ## Authentication <a id="step-0"/>
 
-An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
+An [API key](/docs/platform/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/platform/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/platform/auth/token).
 
 <Aside data-type='important'>
-The examples use [basic authentication](/docs/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/auth/token).
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
 </Aside>
 
 [Sign up](https://ably.com/sign-up) for a free account and create your own API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API key programmatically.
 
-API keys and tokens have a set of [capabilities](/docs/auth/capabilities) assigned to them that specify which operations can be performed on which resources. The following capabilities are available for LiveObjects:
+API keys and tokens have a set of [capabilities](/docs/platform/auth/capabilities) assigned to them that specify which operations can be performed on which resources. The following capabilities are available for LiveObjects:
 
 * `object-subscribe` - grants clients read access to LiveObjects, allowing them to get the root object and subscribe to updates.
 * `object-publish` - grants clients write access to LiveObjects, allowing them to perform mutation operations on objects.
 
 To use LiveObjects, an API key must have at least the `object-subscribe` capability. With only this capability, clients will have read-only access, preventing them from calling mutation methods on LiveObjects.
 
-For the purposes of this guide, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/auth/capabilities) to allow full read and write access.
+For the purposes of this guide, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/platform/auth/capabilities) to allow full read and write access.
 
 ## Install Ably Pub/Sub SDK <a id="step-1"/>
 
diff --git a/src/pages/docs/liveobjects/quickstart/javascript.mdx b/src/pages/docs/liveobjects/quickstart/javascript.mdx
index c634039382..1c4b9f1e4e 100644
--- a/src/pages/docs/liveobjects/quickstart/javascript.mdx
+++ b/src/pages/docs/liveobjects/quickstart/javascript.mdx
@@ -23,22 +23,22 @@ You will learn how to:
 
 ## Authentication <a id="step-0"/>
 
-An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
+An [API key](/docs/platform/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/platform/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/platform/auth/token).
 
 <Aside data-type='important'>
-The examples use [basic authentication](/docs/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/auth/token).
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
 </Aside>
 
 [Sign up](https://ably.com/sign-up) for a free account and create your own API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API key programmatically.
 
-API keys and tokens have a set of [capabilities](/docs/auth/capabilities) assigned to them that specify which operations can be performed on which resources. The following capabilities are available for LiveObjects:
+API keys and tokens have a set of [capabilities](/docs/platform/auth/capabilities) assigned to them that specify which operations can be performed on which resources. The following capabilities are available for LiveObjects:
 
 * `object-subscribe` - grants clients read access to LiveObjects, allowing them to get the channel object and subscribe to updates.
 * `object-publish` - grants clients write access to LiveObjects, allowing them to perform mutation operations on objects.
 
 To use LiveObjects, an API key must have at least the `object-subscribe` capability. With only this capability, clients will have read-only access, preventing them from calling mutation methods on LiveObjects.
 
-For the purposes of this guide, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/auth/capabilities) to allow full read and write access.
+For the purposes of this guide, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/platform/auth/capabilities) to allow full read and write access.
 
 ## Install Ably Pub/Sub SDK <a id="step-1"/>
 
@@ -84,6 +84,10 @@ Reference the Ably Pub/Sub SDK and the Objects plugin within your HTML file:
 
 Instantiate an Ably Realtime client from the Pub/Sub SDK, providing the Objects plugin:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```javascript
 const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', plugins: { LiveObjects } });
diff --git a/src/pages/docs/liveobjects/quickstart/swift.mdx b/src/pages/docs/liveobjects/quickstart/swift.mdx
index bfc09fbf15..6bf28bc4e9 100644
--- a/src/pages/docs/liveobjects/quickstart/swift.mdx
+++ b/src/pages/docs/liveobjects/quickstart/swift.mdx
@@ -20,22 +20,22 @@ You will learn how to:
 
 ## Authentication <a id="step-0"/>
 
-An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
+An [API key](/docs/platform/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/platform/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/platform/auth/token).
 
 <Aside data-type='important'>
-The examples use [basic authentication](/docs/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/auth/token).
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
 </Aside>
 
 [Sign up](https://ably.com/sign-up) for a free account and create your own API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API key programmatically.
 
-API keys and tokens have a set of [capabilities](/docs/auth/capabilities) assigned to them that specify which operations can be performed on which resources. The following capabilities are available for LiveObjects:
+API keys and tokens have a set of [capabilities](/docs/platform/auth/capabilities) assigned to them that specify which operations can be performed on which resources. The following capabilities are available for LiveObjects:
 
 * `object-subscribe` - grants clients read access to LiveObjects, allowing them to get the root object and subscribe to updates.
 * `object-publish` - grants clients write access to LiveObjects, allowing them to perform mutation operations on objects.
 
 To use LiveObjects, an API key must have at least the `object-subscribe` capability. With only this capability, clients will have read-only access, preventing them from calling mutation methods on LiveObjects.
 
-For the purposes of this guide, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/auth/capabilities) to allow full read and write access.
+For the purposes of this guide, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/platform/auth/capabilities) to allow full read and write access.
 
 ## Install Ably Pub/Sub SDK <a id="step-1"/>
 
@@ -65,6 +65,10 @@ import AblyLiveObjects
 
 Instantiate an Ably Realtime client from the Pub/Sub SDK, providing the LiveObjects plugin:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```swift
 let clientOptions = ARTClientOptions(key: "{{API_KEY}}")
diff --git a/src/pages/docs/liveobjects/rest-api-usage.mdx b/src/pages/docs/liveobjects/rest-api-usage.mdx
index b4145d2cd8..67d1789975 100644
--- a/src/pages/docs/liveobjects/rest-api-usage.mdx
+++ b/src/pages/docs/liveobjects/rest-api-usage.mdx
@@ -17,7 +17,7 @@ View the REST API [authentication](/docs/api/rest-api#authentication) documentat
 
 To use LiveObjects, an API key must have at least the `object-subscribe` capability. With only this capability, clients will have read-only access, preventing them from publishing operations.
 
-In order to create or update objects, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/auth/capabilities) to allow full read and write access.
+In order to create or update objects, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/platform/auth/capabilities) to allow full read and write access.
 
 ## Data values <a id="data-values"/>
 
@@ -45,6 +45,10 @@ The key in the `data` object indicates the type of the value:
 
 The following request returns the entire channel object.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```shell
   curl "https://main.realtime.ably.net/channels/my-channel/object" \
diff --git a/src/pages/docs/livesync/index.mdx b/src/pages/docs/livesync/index.mdx
index 8b145df32f..bc4428492b 100644
--- a/src/pages/docs/livesync/index.mdx
+++ b/src/pages/docs/livesync/index.mdx
@@ -19,7 +19,7 @@ Ably's [pub/sub channels](/docs/channels) are the mechanism used by LiveSync for
 
 ## Hosted database connectors <a id="hosted"/>
 
-Take advantage of the Ably hosted database connectors to automatically publish changes from your database as messages on Ably channels. The hosted database connectors support controlling which events are routed to which channels, and using Ably's [Auth](/docs/auth) and [Capabilities](/docs/auth/capabilities) you can control which channels a client is allowed to access.
+Take advantage of the Ably hosted database connectors to automatically publish changes from your database as messages on Ably channels. The hosted database connectors support controlling which events are routed to which channels, and using Ably's [Auth](/docs/platform/auth) and [Capabilities](/docs/platform/auth/capabilities) you can control which channels a client is allowed to access.
 
 Ably provides hosted connectors for:
 * [Postgres](/docs/livesync/postgres)
diff --git a/src/pages/docs/livesync/mongodb/index.mdx b/src/pages/docs/livesync/mongodb/index.mdx
index 2939fb868a..c6930f26aa 100644
--- a/src/pages/docs/livesync/mongodb/index.mdx
+++ b/src/pages/docs/livesync/mongodb/index.mdx
@@ -16,7 +16,7 @@ By using Ably Pub/Sub channels and SDKs, clients subscribing to messages publish
 
 The MongoDB database connector is enabled through an Ably integration rule. The rule will consume document changes from your MongoDB deployment via the MongoDB [Change Streams API](https://www.mongodb.com/docs/manual/changeStreams/). The integration rule exists as a "database connector" component that is entirely provisioned and managed by Ably and is fault-tolerant with automatic fail-over.
 
-When a change event is received over the Change Streams API it is published to an Ably channel. When you configure the integration rule, you can specify how change events are mapped to individual Ably channels. Clients can then subscribe to database changes by subscribing to Ably channels. Ably [Auth](/docs/auth) and [Capabilities](/docs/auth/capabilities) control which channels a client can interact with.
+When a change event is received over the Change Streams API it is published to an Ably channel. When you configure the integration rule, you can specify how change events are mapped to individual Ably channels. Clients can then subscribe to database changes by subscribing to Ably channels. Ably [Auth](/docs/platform/auth) and [Capabilities](/docs/platform/auth/capabilities) control which channels a client can interact with.
 
 ## Integration rule <a id="integration-rule"/>
 
@@ -61,6 +61,10 @@ See the [channels documentation](/docs/pub-sub#subscribe) for further informatio
 
 The following is a simple example of instantiating a realtime client and subscribing to a channel:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```javascript
 // Instantiate the Realtime SDK
@@ -106,9 +110,9 @@ The following is an example of a MongoDB change event that will be carried in th
 For the full schema and fields available on each type of change event, see the MongoDB [Change Event schema](https://www.mongodb.com/docs/v8.0/reference/change-events/) docs.
 </Aside>
 
-In the above example the client is using [basic authentication](/docs/auth/basic). In production applications your clients should use [token authentication](/docs/auth/token).
+In the above example the client is using [basic authentication](/docs/platform/auth/basic). In production applications your clients should use [token authentication](/docs/platform/auth/token).
 
-Clients require the `subscribe` [capability](/docs/auth/capabilities#capabilities-token) for the channels that your integration rule is publishing to.
+Clients require the `subscribe` [capability](/docs/platform/auth/capabilities#capabilities-token) for the channels that your integration rule is publishing to.
 
 The following is an example capability for subscribing to the `myDocuments` channel:
 
diff --git a/src/pages/docs/livesync/postgres/models.mdx b/src/pages/docs/livesync/postgres/models.mdx
index 0801e0391a..068b799aa0 100644
--- a/src/pages/docs/livesync/postgres/models.mdx
+++ b/src/pages/docs/livesync/postgres/models.mdx
@@ -24,13 +24,13 @@ The following diagram provides a simplified overview of the Models SDK:
 
 ## Authenticate <a id="authenticate"/>
 
-An [API key](/docs/auth#api-keys) is required for your frontend app to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
+An [API key](/docs/platform/auth#api-keys) is required for your frontend app to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/platform/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/platform/auth/token).
 
 <Aside data-type='important'>
-The code examples shown as part of the documentation use [basic authentication](/docs/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/auth/token).
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
 </Aside>
 
-API keys and tokens have a set of [capabilities](/docs/auth/capabilities) assigned to them that specify which operations, such as `subscribe` or `publish` can be performed on which resources. To use the Models SDK, the API key requires the following capabilities, these two capabilities are discussed further down the page, but for the time being set these two and you can review them further along:
+API keys and tokens have a set of [capabilities](/docs/platform/auth/capabilities) assigned to them that specify which operations, such as `subscribe` or `publish` can be performed on which resources. To use the Models SDK, the API key requires the following capabilities, these two capabilities are discussed further down the page, but for the time being set these two and you can review them further along:
 
 * `subscribe` for the channels you intend to subscribe to.
 * `history` if you intend to [sync from historical messages](#replay-from-history).
@@ -382,7 +382,7 @@ By default, the events in the buffer are ordered numerically if the `message.id`
 
 ### Channels and models <a id="design-channels-models"/>
 
-In general, when designing your channels and models, aim for a 1:1:1 relationship between channels, models, and your domain model objects. Channels facilitate data partitioning and access control. For instance, in a task management app, each task can be represented by a model with its own channel, ensuring updates are specific to each task. Ably's [capabilities](/docs/auth/capabilities) are applied on a per channel basis allowing fine-grained access control for each data model in your application.
+In general, when designing your channels and models, aim for a 1:1:1 relationship between channels, models, and your domain model objects. Channels facilitate data partitioning and access control. For instance, in a task management app, each task can be represented by a model with its own channel, ensuring updates are specific to each task. Ably's [capabilities](/docs/platform/auth/capabilities) are applied on a per channel basis allowing fine-grained access control for each data model in your application.
 
 For infrequently updated models, grouping them on the same channel may be viable, while frequently changing models benefit from individual channels. Starting with one channel per model and one model per domain object is a good baseline, adjusting as needed.
 
diff --git a/src/pages/docs/livesync/postgres/quickstart.mdx b/src/pages/docs/livesync/postgres/quickstart.mdx
index 525dff7fdd..72850cbcaf 100644
--- a/src/pages/docs/livesync/postgres/quickstart.mdx
+++ b/src/pages/docs/livesync/postgres/quickstart.mdx
@@ -17,7 +17,7 @@ git clone https://github.com/ably-labs/live-comments.git
 
 ### Create an Ably account <a id="step-1"/>
 
-[Sign up](https://ably.com/signup) for a free account to get your own API key. Ensure that your API key includes the `subscribe` and `publish` [capabilities](/docs/auth/capabilities).
+[Sign up](https://ably.com/signup) for a free account to get your own API key. Ensure that your API key includes the `subscribe` and `publish` [capabilities](/docs/platform/auth/capabilities).
 
 ### Set up a database <a id="step-2"/>
 
diff --git a/src/pages/docs/messages/annotations.mdx b/src/pages/docs/messages/annotations.mdx
index 4eafc6dd87..c1b9f4fb54 100644
--- a/src/pages/docs/messages/annotations.mdx
+++ b/src/pages/docs/messages/annotations.mdx
@@ -49,7 +49,7 @@ The `total.v1` summarization method counts the number of annotations of a given
 
 Deleting an annotation decrements the total count for that message.
 
-Using `total.v1` does not attribute counts to individual clients in the summary; it maintains only a simple count per annotation type and does not organize counts by name. [Unidentified](/docs/auth/identified-clients#unidentified) clients can publish `total.v1` annotations. Use the [identified channel rule](/docs/channels#rules) if you want to prevent unidentified clients from publishing annotations.
+Using `total.v1` does not attribute counts to individual clients in the summary; it maintains only a simple count per annotation type and does not organize counts by name. [Unidentified](/docs/platform/auth/identified-clients#unidentified) clients can publish `total.v1` annotations. Use the [identified channel rule](/docs/channels#rules) if you want to prevent unidentified clients from publishing annotations.
 
 If the same client publishes an annotation of a given type to the same message twice, the `total` count is incremented twice.
 
@@ -65,7 +65,7 @@ If the same client publishes an annotation of a given type to the same message t
 
 ### Flag
 
-The `flag.v1` summarization method counts how many distinct clients have published an annotation of a given type and maintains a list of those `clientId`s. Clients must be [identified](/docs/auth/identified-clients) to publish `flag.v1` annotations.
+The `flag.v1` summarization method counts how many distinct clients have published an annotation of a given type and maintains a list of those `clientId`s. Clients must be [identified](/docs/platform/auth/identified-clients) to publish `flag.v1` annotations.
 
 Deleting an annotation decrements the total count for that message and removes the `clientId` from the list of clients that contributed to the summary.
 
@@ -85,7 +85,7 @@ A given client can contribute to the summary only once per annotation type.
 
 ### Distinct
 
-The `distinct.v1` summarization method counts how many unique clients have published an annotation with a given `name` for each annotation type along with the corresponding list of `clientId`s that published it. Clients must be [identified](/docs/auth/identified-clients) to publish `distinct.v1` annotations.
+The `distinct.v1` summarization method counts how many unique clients have published an annotation with a given `name` for each annotation type along with the corresponding list of `clientId`s that published it. Clients must be [identified](/docs/platform/auth/identified-clients) to publish `distinct.v1` annotations.
 
 A given client can contribute to the summary for a particular annotation `name` only once, but the same client may publish additional annotations with different `name`s.
 
@@ -112,7 +112,7 @@ Deleting an annotation removes the `clientId` from the list of clients that cont
 
 ### Unique
 
-The `unique.v1` summarization method counts how many unique clients have published an annotation with a given `name` for each annotation type, while guaranteeing that each client contributes to the summary for only one `name` at a time. The summary for each annotation `name` holds a `total` count of the number of distinct clients that have published an annotation with that `name` along with the corresponding list of `clientId`s that published it. Clients must be [identified](/docs/auth/identified-clients) to publish `unique.v1` annotations.
+The `unique.v1` summarization method counts how many unique clients have published an annotation with a given `name` for each annotation type, while guaranteeing that each client contributes to the summary for only one `name` at a time. The summary for each annotation `name` holds a `total` count of the number of distinct clients that have published an annotation with that `name` along with the corresponding list of `clientId`s that published it. Clients must be [identified](/docs/platform/auth/identified-clients) to publish `unique.v1` annotations.
 
 A given client can contribute to the summary for a particular annotation `name` only once. Publishing an annotation with a different `name` automatically removes that client from the summary for the previous `name` and adds them to the new one, updating the affected total values and list of `clientId`s.
 
@@ -180,10 +180,14 @@ Deleting an annotation removes all contributions made by that `clientId` for tha
 
 To publish an annotation for a message, use the `annotations.publish()` method on a channel. Pass in either a [message](/docs/messages) instance or the `serial` of the message to annotate. This method will publish an annotation with the action `annotation.create`.
 
-Certain annotation summarization methods require a client to be [identified](/docs/auth/identified-clients) for them to be able to publish an annotation. Their `clientId` will then be included in the associated published annotation.
+Certain annotation summarization methods require a client to be [identified](/docs/platform/auth/identified-clients) for them to be able to publish an annotation. Their `clientId` will then be included in the associated published annotation.
 
 Specify the [annotation type](#annotation-types) using the `type` field of the annotation object.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```javascript
 // Create an Ably Realtime client specifying the clientId that will
diff --git a/src/pages/docs/messages/batch.mdx b/src/pages/docs/messages/batch.mdx
index a7ebf6b153..6f68090ea8 100644
--- a/src/pages/docs/messages/batch.mdx
+++ b/src/pages/docs/messages/batch.mdx
@@ -47,6 +47,10 @@ It is possible to publish messages to multiple channels with a single request. A
 
 The following is an example of a batch publish request using the [`request()`](/docs/api/rest-sdk#request) method to query the [batch REST API](/docs/api/rest-api#batch-publish):
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```rest_javascript
 const ablyRest = new Ably.Rest({ key: '{{API_KEY}}' })
diff --git a/src/pages/docs/messages/index.mdx b/src/pages/docs/messages/index.mdx
index d3ecbad18a..8498515f49 100644
--- a/src/pages/docs/messages/index.mdx
+++ b/src/pages/docs/messages/index.mdx
@@ -28,7 +28,7 @@ The following are the properties of a message:
 | **name** | The name of the message |
 | **data** | The contents of the message. Also known as the message payload |
 | **id** | Each message sent through Ably is assigned a unique ID, unless you provide your own ID, which serves as the [idempotency key](/docs/pub-sub/advanced#idempotency) |
-| **clientId** | The [ID of the client](/docs/auth/identified-clients) that published the message |
+| **clientId** | The [ID of the client](/docs/platform/auth/identified-clients) that published the message |
 | **connectionId** | The ID of the connection used to publish the message |
 | **timestamp** | The timestamp of when the message was first received by Ably, as milliseconds since the Unix epoch |
 | **extras** | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include those related to [Push Notifications](/docs/push), [deltas](/docs/channels/options/deltas) and headers |
diff --git a/src/pages/docs/messages/updates-deletes.mdx b/src/pages/docs/messages/updates-deletes.mdx
index 917e92382a..1c7cad7476 100644
--- a/src/pages/docs/messages/updates-deletes.mdx
+++ b/src/pages/docs/messages/updates-deletes.mdx
@@ -43,6 +43,10 @@ To update an existing message, use the `updateMessage()` method on a REST or rea
 
 The message is identified by its `serial`, which is populated by Ably. To update a message, you need its serial - you can get this either from the return value of `publish()`, from a received message via subscription, or by querying history.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```javascript
 const realtime = new Ably.Realtime({ key: '{{API_KEY}}' });
@@ -109,11 +113,11 @@ Ably may opportunistically discard out of date updates to a given message, for e
 
 #### Capabilities <a id="update-capabilities"/>
 
-To update messages, clients need one of the following [capabilities](/docs/auth/capabilities):
+To update messages, clients need one of the following [capabilities](/docs/platform/auth/capabilities):
 
 | Capability | Description |
 | ---------- | ----------- |
-| **message-update-own** | Can update your own messages (more precisely, messages where the original publisher's `clientId` matches the updater's `clientId`, where both are [identified](/docs/auth/identified-clients)). |
+| **message-update-own** | Can update your own messages (more precisely, messages where the original publisher's `clientId` matches the updater's `clientId`, where both are [identified](/docs/platform/auth/identified-clients)). |
 | **message-update-any** | Can update any message on the channel. |
 
 #### Operation metadata <a id="operation-metadata"/>
@@ -200,11 +204,11 @@ Since deletes are just updates with a different action, [as with updates](#updat
 
 #### Capabilities <a id="delete-capabilities"/>
 
-To delete messages, clients need one of the following [capabilities](/docs/auth/capabilities):
+To delete messages, clients need one of the following [capabilities](/docs/platform/auth/capabilities):
 
 | Capability | Description |
 | ---------- | ----------- |
-| **message-delete-own** | Can delete your own messages (more precisely, messages where the original publisher's `clientId` matches the deleter's `clientId`, where both are [identified](/docs/auth/identified-clients)). |
+| **message-delete-own** | Can delete your own messages (more precisely, messages where the original publisher's `clientId` matches the deleter's `clientId`, where both are [identified](/docs/platform/auth/identified-clients)). |
 | **message-delete-any** | Can delete any message on the channel. |
 
 #### Operation metadata <a id="operation-metadata"/>
@@ -322,7 +326,7 @@ This metadata will end up in the message's `version` property. See [Message vers
 
 To retrieve the most recent version of a specific message, use the `getMessage()` method on a REST channel. You can pass either the message's serial identifier as a string, or a message object with a `serial` property.
 
-This operation requires the history [capability](/docs/auth/capabilities).
+This operation requires the history [capability](/docs/platform/auth/capabilities).
 
 <Code>
 ```javascript
@@ -348,7 +352,7 @@ const message = await channel.getMessage(msg);
 
 To retrieve all historical versions of a message, use the `getMessageVersions()` method. This returns a paginated result containing all versions of the message, including the original and all subsequent updates or delete operations, ordered by version.
 
-This operation requires the history [capability](/docs/auth/capabilities).
+This operation requires the history [capability](/docs/platform/auth/capabilities).
 
 <Code>
 ```javascript
diff --git a/src/pages/docs/metadata-stats/metadata/rest.mdx b/src/pages/docs/metadata-stats/metadata/rest.mdx
index bb9fda5836..c29d2ae395 100644
--- a/src/pages/docs/metadata-stats/metadata/rest.mdx
+++ b/src/pages/docs/metadata-stats/metadata/rest.mdx
@@ -19,6 +19,10 @@ Ably SDKs can query this endpoint using the generic [request()](/docs/api/rest-s
 
 The following is an example curl request to retrieve metadata from a channel:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```shell
 curl https://main.realtime.ably.net/channels/<channelId> \
@@ -27,7 +31,7 @@ curl https://main.realtime.ably.net/channels/<channelId> \
 </Code>
 
 <Aside data-type='important'>
-The `channel-metadata` [capability](/docs/auth/capabilities) is required to retrieve the metadata of a channel.
+The `channel-metadata` [capability](/docs/platform/auth/capabilities) is required to retrieve the metadata of a channel.
 </Aside>
 
 ## Retrieve a list of channels <a id="enumerate"/>
@@ -56,7 +60,7 @@ curl https://main.realtime.ably.net/channels \
 Note that this API is intended for occasional use only. For example, to get an initial set of active channels that will be kept up-to-date using the [`[meta]channel.lifecycle`](/docs/metadata-stats/metadata/subscribe#channel-lifecycle) metachannel. The API is heavily rate-limited and only a single in-flight call is permitted to execute at any time. Further concurrent calls will be refused with the error code `42912`.
 
 <Aside data-type='important'>
-The `channel-metadata` [capability](/docs/auth/capabilities) for the wildcard resource `'*'` is required to enumerate a list of active channels.
+The `channel-metadata` [capability](/docs/platform/auth/capabilities) for the wildcard resource `'*'` is required to enumerate a list of active channels.
 </Aside>
 
 ### Known limitations <a id="limitations"/>
diff --git a/src/pages/docs/metadata-stats/metadata/subscribe.mdx b/src/pages/docs/metadata-stats/metadata/subscribe.mdx
index ea3184f7c7..bbbf9a4a5b 100644
--- a/src/pages/docs/metadata-stats/metadata/subscribe.mdx
+++ b/src/pages/docs/metadata-stats/metadata/subscribe.mdx
@@ -24,7 +24,7 @@ The following is a list of available metachannels:
 | **[meta]log:push** | [log](#log): Similar to `[meta]log`, but only for errors that occur during delivery of Push Notifications |
 
 <Aside data-type='important'>
-[Capabilities](/docs/auth/capabilities) for metachannels work almost identically to how they do for regular channels. The only difference is that the resource name in the capability must explicitly include the `[meta]` qualifier.
+[Capabilities](/docs/platform/auth/capabilities) for metachannels work almost identically to how they do for regular channels. The only difference is that the resource name in the capability must explicitly include the `[meta]` qualifier.
 </Aside>
 
 It is never possible to publish or be present on a metachannel, however you can query their [history](/docs/storage-history/history).
diff --git a/src/pages/docs/metadata-stats/stats.mdx b/src/pages/docs/metadata-stats/stats.mdx
index 1d3206f039..a1d14a2229 100644
--- a/src/pages/docs/metadata-stats/stats.mdx
+++ b/src/pages/docs/metadata-stats/stats.mdx
@@ -94,6 +94,10 @@ App-level statistics are also available programmatically using an [Ably SDK](/do
 
 The following is an example of querying app-level statistics using the Ably SDK [`stats` method](/docs/api/rest-sdk/statistics).
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
 const realtime = new Ably.Realtime('{{API_KEY}}');
@@ -650,7 +654,7 @@ Channel metrics include all active [channels](/docs/channels) that are used to s
 
 ### API requests <a id="api"/>
 
-API request metrics include all HTTP requests made to Ably, including those related to [token authentication](/docs/auth/token) and [push notifications](/docs/push). They do not include those requests made to the [Control API](/docs/platform/account/control-api).
+API request metrics include all HTTP requests made to Ably, including those related to [token authentication](/docs/platform/auth/token) and [push notifications](/docs/push). They do not include those requests made to the [Control API](/docs/platform/account/control-api).
 
 | Metric | Description |
 | --- | --- |
diff --git a/src/pages/docs/platform/account/app/api.mdx b/src/pages/docs/platform/account/app/api.mdx
index 2421063578..5e25462b5a 100644
--- a/src/pages/docs/platform/account/app/api.mdx
+++ b/src/pages/docs/platform/account/app/api.mdx
@@ -9,7 +9,7 @@ redirect_from:
 The API keys tab lists all API keys associated with your account and provides information on each key's capabilities and restrictions. You can [create a new API key](#create) and manage an existing one.
 
 <Aside data-type='note'>
-Before setting up multiple API keys with different permissions or sharing API keys with untrusted parties, consider using [token authentication](/docs/auth/token) instead. Token authentication provides more flexible access control and better security for client-side applications.
+Before setting up multiple API keys with different permissions or sharing API keys with untrusted parties, consider using [token authentication](/docs/platform/auth/token) instead. Token authentication provides more flexible access control and better security for client-side applications.
 </Aside>
 
 ## Create a new API key <a id="create"/>
@@ -20,11 +20,11 @@ The following steps create a new API Key:
   * Assign a friendly name.
   * Give the new API key a descriptive name (e.g. chat app key) so it is easy to identify later.
 
-To manage an API key: set [capabilities](/docs/auth/capabilities), define resource restrictions, use revocable tokens for security, and adjust key settings as needed.
+To manage an API key: set [capabilities](/docs/platform/auth/capabilities), define resource restrictions, use revocable tokens for security, and adjust key settings as needed.
 
 ### Capabilities
 
-[Capabilities](/docs/auth/capabilities) provide permissions required for managing message flow, user presence, notifications, channel information, and access controls, these depend on what you require the API key to have access to:
+[Capabilities](/docs/platform/auth/capabilities) provide permissions required for managing message flow, user presence, notifications, channel information, and access controls, these depend on what you require the API key to have access to:
 
 | Capability | Description |
 | ---------- | ----------- |
@@ -48,15 +48,15 @@ Set resource restrictions to control access to channels and queues, ranging from
 | Only queues | Access any queue but not channels. |
 | Selected channels and queues | Specify explicit rules for access. |
 
-When specifying selected channels and queues, you can provide a comma-separated list of resources. Each resource can match a single channel (e.g., `channel-name`) or multiple channels using wildcards (e.g., `namespace:*`). Queues use the prefix `[queue]` and meta channels use `[meta]`. See [capabilities documentation](/docs/auth/capabilities#wildcards) for detailed wildcard syntax.
+When specifying selected channels and queues, you can provide a comma-separated list of resources. Each resource can match a single channel (e.g., `channel-name`) or multiple channels using wildcards (e.g., `namespace:*`). Queues use the prefix `[queue]` and meta channels use `[meta]`. See [capabilities documentation](/docs/platform/auth/capabilities#wildcards) for detailed wildcard syntax.
 
 <Aside data-type='important'>
-A single API key cannot support complex permission combinations, such as publish access on one channel and subscribe access on another. For such requirements, use [token authentication](/docs/auth/token) instead.
+A single API key cannot support complex permission combinations, such as publish access on one channel and subscribe access on another. For such requirements, use [token authentication](/docs/platform/auth/token) instead.
 </Aside>
 
 ### Revocable tokens
 
-[Revocable tokens](/docs/auth/revocation#revocable-tokens) enhance security by allowing shorter token lifetimes and the ability to revoke tokens issued via the API key.
+[Revocable tokens](/docs/platform/auth/revocation#revocable-tokens) enhance security by allowing shorter token lifetimes and the ability to revoke tokens issued via the API key.
 
 | Option | Description |
 | ------ | ----------- |
diff --git a/src/pages/docs/platform/account/control-api.mdx b/src/pages/docs/platform/account/control-api.mdx
index 844f23f165..d6526d7627 100644
--- a/src/pages/docs/platform/account/control-api.mdx
+++ b/src/pages/docs/platform/account/control-api.mdx
@@ -142,7 +142,7 @@ In the [Ably dashboard](https://ably.com/accounts/any) select the app you want t
 
 ![Application Settings](../../../../images/content/screenshots/control-api/application-settings.png)
 
-The **App ID** is displayed under **Application settings**. It is also the first part of your API key for that app. For example, if your API key is `28AB6c.DEFi0Q`, then the App ID is `28AB6c`. You can find out more in the Ably Help Center article [what is an app API key?](/docs/auth#api-key).
+The **App ID** is displayed under **Application settings**. It is also the first part of your API key for that app. For example, if your API key is `28AB6c.DEFi0Q`, then the App ID is `28AB6c`. You can find out more in the Ably Help Center article [what is an app API key?](/docs/platform/auth#api-key).
 
 ## Examples <a id="examples"/>
 
@@ -463,7 +463,7 @@ You can use the Control API to manage Ably API keys. The main operations are:
 * Update a key
 * Revoke a key
 
-Control API enables you to create a key that has different [capabilities](/docs/auth/capabilities) for different channels.
+Control API enables you to create a key that has different [capabilities](/docs/platform/auth/capabilities) for different channels.
 
 #### List API keys <a id="examples-keys-list"/>
 
diff --git a/src/pages/docs/platform/account/enterprise-customization.mdx b/src/pages/docs/platform/account/enterprise-customization.mdx
index 92197df19d..cfcb397ca6 100644
--- a/src/pages/docs/platform/account/enterprise-customization.mdx
+++ b/src/pages/docs/platform/account/enterprise-customization.mdx
@@ -67,7 +67,7 @@ To use a custom endpoint, perform the following steps:
 
 ### Decide whether to use an Ably subdomain, or your own domain
 
-Ably client libraries connect to the `main.realtime.ably.net` domain by default. This domain is used by both WebSocket and other realtime connections from the Ably client libraries, as well as all REST-based requests. It is optimized for all standard HTTP-based request types, including all [REST requests](/docs/api/rest-api), [authentication requests](/docs/auth), and Comet and JSONP fallback when WebSockets cannot be used.
+Ably client libraries connect to the `main.realtime.ably.net` domain by default. This domain is used by both WebSocket and other realtime connections from the Ably client libraries, as well as all REST-based requests. It is optimized for all standard HTTP-based request types, including all [REST requests](/docs/api/rest-api), [authentication requests](/docs/platform/auth), and Comet and JSONP fallback when WebSockets cannot be used.
 
 When you request a custom endpoint, you have the following options:
 
diff --git a/src/pages/docs/platform/account/users.mdx b/src/pages/docs/platform/account/users.mdx
index ad020cdaba..496b46f06a 100644
--- a/src/pages/docs/platform/account/users.mdx
+++ b/src/pages/docs/platform/account/users.mdx
@@ -29,7 +29,7 @@ User roles have the following permissions:
 | Configure own [2FA](/docs/platform/account/2fa) | ✓ | - | ✓ | ✓ |
 | [Invite new users](#invite) | - | - | ✓ | ✓ |
 | [Remove existing users](#remove) | - | - | ✓ | ✓ |
-| Manage [API keys](/docs/auth) | - | - | ✓ | ✓ |
+| Manage [API keys](/docs/platform/auth) | - | - | ✓ | ✓ |
 | Manage app configuration | - | - | ✓ | ✓ |
 | Manage app settings | - | - | ✓ | ✓ |
 | Create apps | - | - | ✓ | ✓ |
diff --git a/src/pages/docs/platform/ai-llms/index.mdx b/src/pages/docs/platform/ai-llms/index.mdx
index e350126b0e..2db961595e 100644
--- a/src/pages/docs/platform/ai-llms/index.mdx
+++ b/src/pages/docs/platform/ai-llms/index.mdx
@@ -16,7 +16,7 @@ Every documentation page is available as clean markdown by appending `.md` to th
 
 - `https://ably.com/docs/channels.md` - Channels documentation
 - `https://ably.com/docs/chat/rooms.md` - Chat rooms documentation
-- `https://ably.com/docs/auth.md` - Authentication documentation
+- `https://ably.com/docs/platform/auth.md` - Authentication documentation
 
 These markdown versions strip out navigation and UI elements, providing clean content that LLMs can easily parse and understand.
 
@@ -112,7 +112,7 @@ Use **API reference docs** when:
 
 Never infer or approximate APIs—always rely on API reference pages.
 
-#### Product and feature docs (`/docs/{product}/`, `/docs/channels/`, `/docs/auth/`, etc.)
+#### Product and feature docs (`/docs/{product}/`, `/docs/channels/`, `/docs/platform/auth/`, etc.)
 Use **product and feature docs** for:
 - Understanding how specific features work
 - Configuration options and parameters
diff --git a/src/pages/docs/auth/basic.mdx b/src/pages/docs/platform/auth/basic.mdx
similarity index 91%
rename from src/pages/docs/auth/basic.mdx
rename to src/pages/docs/platform/auth/basic.mdx
index bdcc9a6b02..103112855e 100644
--- a/src/pages/docs/auth/basic.mdx
+++ b/src/pages/docs/platform/auth/basic.mdx
@@ -1,9 +1,11 @@
 ---
 title: Basic auth
 meta_description: "Basic authentication allows you to authenticate a secure server using an Ably API key and secret."
+redirect_from:
+  - /docs/auth/basic
 ---
 
-Basic authentication is the simplest way to authenticate with Ably. It requires passing an [API key](/docs/auth#api-key) when instancing an SDK.
+Basic authentication is the simplest way to authenticate with Ably. It requires passing an [API key](/docs/platform/auth#api-key) when instancing an SDK.
 
 <Aside data-type='important'>
 Private API keys should never be shared with untrusted parties, and as such, should only be used by your trusted secure servers when authenticating with Ably.
@@ -122,7 +124,7 @@ The process used by Ably SDKs to authenticate with Ably using basic authenticati
 Ably recommends that basic authentication is only used server-side because of the following potential issues:
 
 * The secret is passed directly by the client to Ably, so it is only permitted for connections that are over TLS, to prevent the key secret being intercepted.
-* All of the configured [capabilities](/docs/auth/capabilities) of the key are implicitly possible in any request, and clients that legitimately obtain this key may then abuse the rights for that key.
+* All of the configured [capabilities](/docs/platform/auth/capabilities) of the key are implicitly possible in any request, and clients that legitimately obtain this key may then abuse the rights for that key.
 * A client that authenticates using an API key can claim any client ID it chooses. Therefore this client ID cannot be trusted to represent the genuine identity of the client. Client IDs should be assigned by the server, once the client's credentials have been authenticated.
 
 <Aside data-type='note'>
diff --git a/src/pages/docs/auth/capabilities.mdx b/src/pages/docs/platform/auth/capabilities.mdx
similarity index 62%
rename from src/pages/docs/auth/capabilities.mdx
rename to src/pages/docs/platform/auth/capabilities.mdx
index 34a9d2f663..cab4b882c9 100644
--- a/src/pages/docs/auth/capabilities.mdx
+++ b/src/pages/docs/platform/auth/capabilities.mdx
@@ -1,13 +1,15 @@
 ---
 title: Capabilities
 meta_description: "Capabilities define which operations can be carried out on which channels by a client."
+redirect_from:
+  - /docs/auth/capabilities
 ---
 
 API keys and Ably-compatible tokens, have a set of capabilities assigned to them that specify which operations (such as subscribe or publish) can be performed on which channels.
 
 API keys are long-lived, secret and typically not shared with clients. API key capabilities are configured using the [dashboard](https://ably.com/dashboard), or using the [Control API](/docs/platform/account/control-api).
 
-Ably-compatible tokens are designed to be shared with untrusted clients, are short-lived, and can be configured and issued programmatically. For restricting client access to channels, tokens provide far more flexibility and security than API key capabilities. See [selecting an authentication mechanism](/docs/auth#selecting-auth) to understand why token authentication is the preferred option in most scenarios.
+Ably-compatible tokens are designed to be shared with untrusted clients, are short-lived, and can be configured and issued programmatically. For restricting client access to channels, tokens provide far more flexibility and security than API key capabilities. See [selecting an authentication mechanism](/docs/platform/auth#selecting-auth) to understand why token authentication is the preferred option in most scenarios.
 
 ### Capability changes and existing connections <a id="capability-changes-existing-connections"/>
 
@@ -15,9 +17,9 @@ Ably-compatible tokens are designed to be shared with untrusted clients, are sho
 When you change a key's capabilities in the dashboard, existing connections using that key do **not** receive the updated capabilities immediately. Connections must be closed and re-opened to pick up the new capabilities.
 </Aside>
 
-Once created, it's best to think of keys and tokens as being immutable. To modify the permissions granted to existing connections, the recommended approach is to use [token authentication](/docs/auth/token) and issue the client a new token with the updated permissions you want them to have.
+Once created, it's best to think of keys and tokens as being immutable. To modify the permissions granted to existing connections, the recommended approach is to use [token authentication](/docs/platform/auth/token) and issue the client a new token with the updated permissions you want them to have.
 
-The one exception is if a key is revoked entirely, in which case all connections using that key (or a token derived from that key) will be forcibly terminated. See [token revocation](/docs/auth/revocation) for more information.
+The one exception is if a key is revoked entirely, in which case all connections using that key (or a token derived from that key) will be forcibly terminated. See [token revocation](/docs/platform/auth/revocation) for more information.
 
 ## Resource names and wildcards <a id="wildcards"/>
 
@@ -71,7 +73,7 @@ Ably does not provide numeric limits on channel access. Control channel access u
 
 Channel access is controlled through:
 
-* [Token authentication](/docs/auth/token) to restrict access by issuing tokens with specific capabilities to authorized users.
+* [Token authentication](/docs/platform/auth/token) to restrict access by issuing tokens with specific capabilities to authorized users.
 * Specific `clientId` values in tokens to ensure only certain users can access particular channels.
 * Granting or restricting specific operations (`subscribe`, `publish`, `presence`) on channels through capability configurations.
 
@@ -87,7 +89,7 @@ Channel mode flags offer the ability for clients to use different capabilities f
 
 ## API key capabilities <a id="capabilities-key"/>
 
-An [Ably API key](/docs/auth#api-key) can have a single set of permissions, applied to any number of [channels](/docs/channels) or [queues](/docs/platform/integrations/queues).
+An [Ably API key](/docs/platform/auth#api-key) can have a single set of permissions, applied to any number of [channels](/docs/channels) or [queues](/docs/platform/integrations/queues).
 
 You can also choose whether to restrict the API key to only channels, only [queues](/docs/platform/integrations/queues), or to match a set of channel or queue names. If you've chosen to restrict the API key to *selected channels and queues*, you can use a comma separated list of resources the API key can access, making use of wildcards to provide access to areas of your app. It is worth noting an API key will provide the same permissions to all resources it has access to.
 
@@ -103,75 +105,94 @@ Ably Tokens and JWTs are issued from an existing API key and their capabilities
 
 If an API key must be shared with a third party, then it is recommended that [the principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) is considered, assigning only the capabilities needed by that third party. Thus, any Ably requests authenticated using that API key or Ably-compatible tokens associated with that API key, will be restricted to the capabilities assigned to the API key.
 
-Capabilities can be set when creating a token or token request, as shown in the following example:
+#### Using JWT (recommended) <a id="jwt-capabilities"/>
+
+Set capabilities in a JWT using the `x-ably-capability` claim. No Ably SDK is required—any JWT library will work:
 
 <Code>
 ```javascript
-  var tokenParams = { clientId: 'foo', capability: JSON.stringify(capability) };
-  const tokenRequest = await ably.auth.createTokenRequest(tokenParams);
-```
+// Server-side: Create JWT with capabilities using any JWT library
+import jwt from 'jsonwebtoken';
 
-```python
-token_params = {
-    'client_id': 'foo',
-    'capability': json.dumps(capability)
-}
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
 
-token_request = await ably_rest.auth.create_token_request(token_params)
+const ablyJwt = jwt.sign(
+  {
+    'x-ably-capability': JSON.stringify({
+      'your-namespace:*': ['publish', 'subscribe', 'presence'],
+      'notifications': ['subscribe'],
+    }),
+    'x-ably-clientId': userId,
+  },
+  keySecret,
+  { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+);
 ```
 
-```php
-$tokenParams = [
-    'clientId' => 'client@example.com',
-    'capability' => json_encode($capability)
-];
-$tokenRequest = $rest->auth->createTokenRequest($tokenParams);
+```python
+# Server-side: Create JWT with capabilities using any JWT library
+import jwt
+import json
+import time
+import os
+
+key_name, key_secret = os.environ['ABLY_API_KEY'].split(':')
+
+now = int(time.time())
+ably_jwt = jwt.encode(
+    {
+        'iat': now,
+        'exp': now + 3600,
+        'x-ably-capability': json.dumps({
+            'your-namespace:*': ['publish', 'subscribe', 'presence'],
+            'notifications': ['subscribe'],
+        }),
+        'x-ably-clientId': user_id,
+    },
+    key_secret,
+    algorithm='HS256',
+    headers={'kid': key_name}
+)
 ```
+</Code>
 
-```go
-rest, _ := ably.NewREST(
-  ably.WithKey("xVLyHw.I2jW-g:dOTlhEt-nIubVAPMAUJnGv-_F8BZ7xNYnXdajpGaISg"))
+#### Using TokenRequest (alternative) <a id="tokenrequest-capabilities"/>
 
-// Define the capability
-capability := map[string][]string{
-  "*": {"*"},
-}
+If JWT is not suitable, use the Ably SDK to create a TokenRequest with capabilities:
 
-capabilityJSON, err := json.Marshal(capability)
-if err != nil {
-  log.Fatalf("Failed to marshal capability: %v", err)
-}
-
-// Define the token parameters
-tokenParams := &ably.TokenParams{
-  ClientID:   "foo",
-  Capability: string(capabilityJSON),
-}
-
-// Create a token request
-tokenRequest, err := rest.Auth.CreateTokenRequest(tokenParams)
-if err != nil {
-  log.Fatalf("Failed to create token request: %v", err)
-}
+<Code>
+```javascript
+// Server-side with Ably SDK
+const ably = new Ably.Rest(process.env.ABLY_API_KEY);
+const tokenRequest = await ably.auth.createTokenRequest({
+  clientId: 'user-123',
+  capability: JSON.stringify({
+    'your-namespace:*': ['publish', 'subscribe'],
+  }),
+});
 ```
 
-```flutter
-final tokenParams = ably.TokenParams(
-  clientId: 'foo',
-  capability: jsonEncode(capability),
-);
-
-final tokenRequest = await rest.auth.createTokenRequest(tokenParams: tokenParams);
+```python
+# Server-side with Ably SDK
+ably = AblyRest(os.environ['ABLY_API_KEY'])
+token_request = await ably.auth.create_token_request({
+    'client_id': 'user-123',
+    'capability': json.dumps({
+        'your-namespace:*': ['publish', 'subscribe'],
+    }),
+})
 ```
 </Code>
 
+See [token authentication](/docs/platform/auth/token#token-request) for complete TokenRequest examples in all languages.
+
 ### Token capability determination <a id="capability-determination"/>
 
 The capabilities for tokens are determined based on those of the issuing API key and those requested by the token.
 
 #### Ably Token without capabilities <a id="ably-token-all"/>
 
-If no capability is specified in an Ably `TokenRequest`, then the [Ably Token](/docs/auth/token#tokens) will be given the full set of capabilities assigned to the issuing key.
+If no capability is specified in an Ably `TokenRequest`, then the [Ably Token](/docs/platform/auth/token#tokens) will be given the full set of capabilities assigned to the issuing key.
 
 Using the following example, an API key exists with the listed capabilities. If an Ably Token is requested without specifying any capabilities then the `TokenRequest` is treated as requesting all capabilities, i.e. `{"[*]*":["*"]}`. This will result in the Ably Token receiving all the capabilities of the API key.
 
@@ -179,8 +200,8 @@ Using the following example, an API key exists with the listed capabilities. If
 ```javascript
   // API key capabilities:
   {
-    'chat': ['publish', 'subscribe', 'presence'],
-    'status': ['subscribe']
+    'your-namespace': ['publish', 'subscribe', 'presence'],
+    'notifications': ['subscribe']
   }
 
   // Token request that doesn't specify any capabilities:
@@ -188,19 +209,19 @@ Using the following example, an API key exists with the listed capabilities. If
 
   // Resulting token capabilities:
   {
-    'chat': ['publish', 'subscribe', 'presence'],
-    'status': ['subscribe']
+    'your-namespace': ['publish', 'subscribe', 'presence'],
+    'notifications': ['subscribe']
   }
 ```
 
 ```python
 # API key capabilities:
 # {
-#   "chat": ["publish", "subscribe", "presence"],
-#   "status": ["subscribe"]
+#   "your-namespace": ["publish", "subscribe", "presence"],
+#   "notifications": ["subscribe"]
 # }
 
-// Token request that doesn't specify any capabilities:
+# Token request that doesn't specify any capabilities:
 token = await ably.auth.create_token_request(
 {
     "clientId": "client@example.com",
@@ -209,37 +230,16 @@ token = await ably.auth.create_token_request(
 
 # Resulting token capabilities:
 # {
-# "chat": ["publish", "subscribe", "presence"],
-# "status": ["subscribe"]
+# "your-namespace": ["publish", "subscribe", "presence"],
+# "notifications": ["subscribe"]
 # }
 ```
 
-```php
-// API key capabilities:
-//{
-//  'chat': ['publish', 'subscribe', 'presence'],
-//  'status': ['subscribe']
-//}
-
-// Token request that doesn't specify any capabilities:
-$tokenParams = [
-    'clientId' => 'client@example.com',
-    'ttl' => 3600 * 1000, // ms
-];
-$tokenRequest = $rest->auth->requestToken($tokenParams);
-
-// Resulting token capabilities:
-//{
-//  'chat': ['publish', 'subscribe', 'presence'],
-//  'status': ['subscribe']
-//}
-```
-
 ```go
 // API key capabilities:
 // {
-//   "chat": ["publish", "subscribe", "presence"],
-//   "status": ["subscribe"]
+//   "your-namespace": ["publish", "subscribe", "presence"],
+//   "notifications": ["subscribe"]
 // }
 
 rest, _ := ably.NewREST(
@@ -259,24 +259,8 @@ if err != nil {
 
 // Resulting token capabilities:
 // {
-// "chat": ["publish", "subscribe", "presence"],
-// "status": ["subscribe"]
-// }
-```
-
-```flutter
-// API key capabilities:
-// {
-//    'chat': ['publish', 'subscribe', 'presence'],
-//    'status': ['subscribe']
-// }
-
-final tokenRequest = await realtime.auth.requestToken(tokenParams: tokenParams);
-
-// Resulting token capabilities:
-// {
-//    'chat': ['publish', 'subscribe', 'presence'],
-//    'status': ['subscribe']
+// "your-namespace": ["publish", "subscribe", "presence"],
+// "notifications": ["subscribe"]
 // }
 ```
 </Code>
@@ -285,44 +269,44 @@ final tokenRequest = await realtime.auth.requestToken(tokenParams: tokenParams);
 
 If a set of capabilities are requested, then the Ably Token will be assigned the intersection of the requested capability and the capability of the issuing key.
 
-Using the following example, an API key exists with the listed capabilities. If an [Ably Token](/docs/auth/token#tokens) is requested and specifies a set of capabilities, then the resulting token will only receive those capabilities that intersect. The capabilities of a token cannot exceed those of the issuing API key.
+Using the following example, an API key exists with the listed capabilities. If an [Ably Token](/docs/platform/auth/token#tokens) is requested and specifies a set of capabilities, then the resulting token will only receive those capabilities that intersect. The capabilities of a token cannot exceed those of the issuing API key.
 
 <Code>
 ```javascript
   // API key capabilities:
   {
-    'chat:*': ['publish', 'subscribe', 'presence'],
-    'status': ['subscribe', 'history'],
+    'your-namespace:*': ['publish', 'subscribe', 'presence'],
+    'notifications': ['subscribe', 'history'],
     'alerts': ['subscribe']
   }
 
   // Token request that specifies capabilities:
   const tokenDetails = await auth.requestToken({ capability: {
-    'chat:bob': ['subscribe'], // only 'subscribe' intersects
-    'status': ['*'], // '*'' intersects with 'subscribe'
-    'secret': ['publish', 'subscribe'] // key does not have access to 'secret' channel
+    'your-namespace:user-123': ['subscribe'], // only 'subscribe' intersects
+    'notifications': ['*'], // '*'' intersects with 'subscribe'
+    'private': ['publish', 'subscribe'] // key does not have access to 'private' channel
   }});
 
   // Resulting token capabilities:
   {
-    'chat:bob': ['subscribe'],
-    'status': ['subscribe', 'history']
+    'your-namespace:user-123': ['subscribe'],
+    'notifications': ['subscribe', 'history']
   }
 ```
 
 ```python
 # API key capabilities:
 # {
-#   "chat:*": ["publish", "subscribe", "presence"],
-#   "status": ["subscribe", "history"],
+#   "your-namespace:*": ["publish", "subscribe", "presence"],
+#   "notifications": ["subscribe", "history"],
 #   "alerts": ["subscribe"]
 # }
 
 # Token request that specifies capabilities:
 capabilities = {
-    "chat:bob": ["subscribe"],  # only "subscribe" intersects
-    "status": ["*"],  # "*" intersects with "subscribe"
-    "secret": ["publish", "subscribe"]  # key does not have access to "secret" channel
+    "your-namespace:user-123": ["subscribe"],  # only "subscribe" intersects
+    "notifications": ["*"],  # "*" intersects with "subscribe"
+    "private": ["publish", "subscribe"]  # key does not have access to "private" channel
 }
 
 token_details = await ably_rest.auth.request_token({
@@ -331,48 +315,16 @@ token_details = await ably_rest.auth.request_token({
 
 # Resulting token capabilities:
 # {
-#   "chat:bob": ["subscribe"],
-#   "status": ["subscribe", "history"]
+#   "your-namespace:user-123": ["subscribe"],
+#   "notifications": ["subscribe", "history"]
 # }
 ```
 
-```php
-/**
-  * API key capabilities:
-  * {
-  *   'chat:*': ['publish', 'subscribe', 'presence'],
-  *   'status': ['subscribe', 'history'],
-  *   'alerts': ['subscribe']
-  * }
-  */
-
-// Token request that specifies capabilities:
-$capabilities = [
-    'chat:bob' => ['subscribe'],  // only 'subscribe' intersects
-    'status' => ['*'],  // '*' intersects with 'subscribe'
-    'secret' => ['publish', 'subscribe']  // key does not have access to 'secret' channel
-];
-
-$tokenDetails = $rest
-    ->auth
-    ->requestToken(
-        ['capability' => json_encode($capabilities)]
-    );
-
-/**
-  * Resulting token capabilities:
-  * {
-  *   'chat:bob': ['subscribe'],
-  *   'status': ['subscribe', 'history']
-  * }
-  */
-```
-
 ```go
 // API key capabilities:
 // {
-//   "chat:*": ["publish", "subscribe", "presence"],
-//   "status": ["subscribe", "history"],
+//   "your-namespace:*": ["publish", "subscribe", "presence"],
+//   "notifications": ["subscribe", "history"],
 //   "alerts": ["subscribe"]
 // }
 
@@ -382,9 +334,9 @@ rest, _ := ably.NewREST(
 
 // Define the capabilities
 capabilities := map[string][]string{
-  "chat:bob": {"subscribe"},
-  "status":   {"*"},
-  "secret":   {"publish", "subscribe"},
+  "your-namespace:user-123": {"subscribe"},
+  "notifications":           {"*"},
+  "private":                 {"publish", "subscribe"},
 }
 
 capabilitiesJSON, err := json.Marshal(capabilities)
@@ -405,34 +357,8 @@ if err != nil {
 
 // Resulting token capabilities:
 // {
-//   "chat:bob": ["subscribe"],
-//   "status": ["subscribe", "history"]
-// }
-```
-
-```flutter
-// API key capabilities:
-// {
-//   'chat:bob': ['subscribe'],
-//   'status': ['*'],
-//   'secret': ['publish', 'subscribe']
-// }
-
-final tokenParams = ably.TokenParams(
-  capability: jsonEncode({
-    'chat:bob': ['subscribe'],
-    'status': ['*'],
-    'secret': ['publish', 'subscribe']
-  }),
-);
-
-final tokenDetails = await rest.auth.requestToken(tokenParams: tokenParams);
-
-// Resulting token capabilities:
-// {
-//   'chat:bob': ['subscribe'],
-//   'secret': ['publish','subscribe']
-//   'status': ['subscribe', 'history']
+//   "your-namespace:user-123": ["subscribe"],
+//   "notifications": ["subscribe", "history"]
 // }
 ```
 </Code>
@@ -441,56 +367,38 @@ final tokenDetails = await rest.auth.requestToken(tokenParams: tokenParams);
 
 If a set of capabilities are requested, and the intersection between those and the API key's capabilities is empty, then the `TokenRequest` will result in an error.
 
-Using the following example, an API key exists with the listed capabilities. If an [Ably Token](/docs/auth/token#tokens) is requested that specifies a set of capabilities, and there is no intersection between the capabilities of the issuing API key and requested token, then the token request will be rejected. In the following example, the callback will be returned with an error.
+Using the following example, an API key exists with the listed capabilities. If an [Ably Token](/docs/platform/auth/token#tokens) is requested that specifies a set of capabilities, and there is no intersection between the capabilities of the issuing API key and requested token, then the token request will be rejected. In the following example, the callback will be returned with an error.
 
 <Code>
 ```javascript
   // API key capabilities:
   {
-    'chat': ['*']
+    'your-namespace': ['*']
   }
 
   // Token request that specifies capabilities:
   const tokenDetails = await auth.requestToken({ capability: {
-    'status': ['*']
+    'other-namespace': ['*']
   }});
 ```
 
 ```python
 # API key capabilities:
 # {
-#   "chat": ["*"]
+#   "your-namespace": ["*"]
 # }
 
 token_details = await ably_rest.auth.request_token({
     'capability': json.dumps({
-        {
-            "status": ["*"]
-        }
+        "other-namespace": ["*"]
     })
 })
 ```
 
-```php
-/**
-  * API key capabilities:
-  * {
-  *   'chat': ['*']
-  * }
-  */
-
-// Token request that specifies capabilities:
-$tokenDetails = $rest
-    ->auth
-    ->requestToken(
-        ['capability' => json_encode(['status' => ['*']])]
-    );
-```
-
 ```go
 // API key capabilities:
 // {
-//   "chat": ["*"]
+//   "your-namespace": ["*"]
 // }
 
 rest, _ := ably.NewREST(
@@ -498,7 +406,7 @@ rest, _ := ably.NewREST(
 
 // Define the capabilities
 capabilities := map[string][]string{
-  "status": {"*"},
+  "other-namespace": {"*"},
 }
 
 capabilitiesJSON, err := json.Marshal(capabilities)
@@ -517,31 +425,21 @@ if err != nil {
   log.Fatalf("Failed to request token: %v", err)
 }
 ```
-
-```flutter
-// API key capabilities:
-// {
-//   'status': ['*']
-// }
-final tokenParams = ably.TokenParams(
-  capability: jsonEncode({
-    'status': ['*']
-  }),
-);
-
-final tokenDetails = await realtime.auth.requestToken(tokenParams: tokenParams);
-```
 </Code>
 
 #### Ably JWT capability determination <a id="ably-jwt"/>
 
-Capabilities are determined for [Ably JWTs](/docs/auth/token#jwt) in the following way:
+Capabilities are determined for [Ably JWTs](/docs/platform/auth/token#jwt) in the following way:
 
 * The capabilities granted to an Ably JWT will be the intersection of the capabilities within the Ably JWT and the capabilities of the associated API key.
 * If the set of capabilities within the Ably JWT have no intersection with the capabilities of the API key, then an error will instead be returned.
 
 ## Custom restrictions on channels <a id="custom-restrictions"/>
 
+<Aside data-type='important'>
+**JWT-only feature:** Channel-scoped user claims are only available when using [Ably JWT authentication](/docs/platform/auth/token#choosing-jwt). They are not available with TokenRequest authentication. See [JWT-only features](/docs/platform/auth/token#jwt-only-features) for a complete list of capabilities exclusive to JWT authentication.
+</Aside>
+
 It is possible for JWTs to contain authenticated claims for users that can be used to allow or disallow certain interactions in your channels.
 
 Messages can be annotated with trusted metadata copied from the client's authentication token by Ably servers. Clients are unable to directly publish messages with user claim metadata, and claims contained within the authentication token are signed to prevent tampering. Claims can be scoped to individual channels or to namespaces of [channels](/docs/channels). The most specific user claim will be added to the message as part of the `extras` object. Note that this does not apply to presence or metadata messages.
@@ -555,8 +453,8 @@ To set the trusted fields you need to include `ably.channel.*` in your JWT authe
     'name': 'John Doe',
     'x-ably-capability': <...>,
     'x-ably-clientId': <...>,
-    'ably.channel.chat1': 'admin', // the user is an admin for the chat1 channel
-    'ably.channel.chat:*': 'moderator', // the user is a moderator in channels within the chat namespace
+    'ably.channel.your-channel': 'admin', // the user is an admin for a specific channel
+    'ably.channel.your-namespace:*': 'moderator', // the user is a moderator in all channels within a namespace
     'ably.channel.*': 'guest', // the user is a guest in all other channels
   }
 ```
@@ -567,47 +465,23 @@ claims = {
     "name": "John Doe",
     "x-ably-capability": "<...>",
     "x-ably-clientId": "<...>",
-    "ably.channel.chat1": "admin",       # the user is an admin for the chat1 channel
-    "ably.channel.chat:*": "moderator",  # the user is a moderator in channels within the chat namespace
+    "ably.channel.your-channel": "admin",       # the user is an admin for a specific channel
+    "ably.channel.your-namespace:*": "moderator",  # the user is a moderator in all channels within a namespace
     "ably.channel.*": "guest"            # the user is a guest in all other channels
 }
 ```
 
-```php
-$claims = [
-    'sub' => '1234567890',
-    'name' => 'John Doe',
-    'x-ably-capability' => '<...>',
-    'x-ably-clientId' => '<...>',
-    'ably.channel.chat1' => 'admin',         // the user is an admin for the chat1 channel
-    'ably.channel.chat =>*' => 'moderator',  // the user is a moderator in channels within the chat namespace
-    'ably.channel.*' => 'guest'              // the user is a guest in all other channels
-];
-```
-
 ```go
 claims := map[string]interface{}{
-  "sub":                   "1234567890",
-  "name":                  "John Doe",
-  "x-ably-capability":     "<...>",
-  "x-ably-clientId":       "<...>",
-  "ably.channel.chat1":    "admin",
-  "ably.channel.chat:*":   "moderator",
-  "ably.channel.*":        "guest",
+  "sub":                            "1234567890",
+  "name":                           "John Doe",
+  "x-ably-capability":              "<...>",
+  "x-ably-clientId":                "<...>",
+  "ably.channel.your-channel":      "admin",
+  "ably.channel.your-namespace:*":  "moderator",
+  "ably.channel.*":                 "guest",
 }
 ```
-
-```flutter
-final claims = {
-  'sub': '1234567890',
-  'name': 'John Doe',
-  'x-ably-capability': '<...>',
-  'x-ably-clientId': '<...>',
-  'ably.channel.chat1': 'admin',
-  'ably.channel.chat:*': 'moderator',
-  'ably.channel.*': 'guest',
-};
-```
 </Code>
 
 The claims from the token are copied into messages, allowing them to be checked for permission:
@@ -638,17 +512,14 @@ func fromModerator(message map[string]interface{}) bool {
 	return false
 }
 ```
-
-```flutter
-bool fromModerator(Message message) {
-  final userClaim = message.extras['userClaim'];
-  return userClaim != null && userClaim == 'moderator';
-}
-```
 </Code>
 
 ## Using JWT for per connection publish rate limits <a id="jwt-limits"/>
 
+<Aside data-type='important'>
+**JWT-only feature:** Per-connection publish rate limits are only available when using [Ably JWT authentication](/docs/platform/auth/token#choosing-jwt). They are not available with TokenRequest authentication. See [JWT-only features](/docs/platform/auth/token#jwt-only-features) for a complete list of capabilities exclusive to JWT authentication.
+</Aside>
+
 JWTs may specify publish rate limits for a user on particular channels. These limits can be used to prevent any individual user from sending an excessive number of messages in a short period of time.
 
 An example use case is in a large live chat where you may wish to limit users to posting messages no more than once every 10 seconds.
@@ -666,8 +537,8 @@ The following is an example of setting different rate limits for different chann
     'name': 'John Doe',
     'x-ably-capability': <...>,
     'x-ably-clientId': <...>,
-    'ably.limits.publish.perAttachment.maxRate.chat1': 10, // the user can publish 10 messages per second in channel chat1
-    'ably.limits.publish.perAttachment.maxRate.chat:*': 0.1 // the user can publish a message every 10 seconds in all channels within the chat namespace
+    'ably.limits.publish.perAttachment.maxRate.your-channel': 10, // the user can publish 10 messages per second in a specific channel
+    'ably.limits.publish.perAttachment.maxRate.your-namespace:*': 0.1 // the user can publish a message every 10 seconds in all channels within a namespace
   }
 ```
 
@@ -677,41 +548,19 @@ claims = {
     "name": "John Doe",
     "x-ably-capability": "<...>",
     "x-ably-clientId": "<...>",
-    "ably.limits.publish.perAttachment.maxRate.chat1": 10,   # the user can publish 10 messages per second in channel chat1
-    "ably.limits.publish.perAttachment.maxRate.chat:*": 0.1  # the user can publish a message every 10 seconds in all channels within the chat namespace
+    "ably.limits.publish.perAttachment.maxRate.your-channel": 10,   # the user can publish 10 messages per second in a specific channel
+    "ably.limits.publish.perAttachment.maxRate.your-namespace:*": 0.1  # the user can publish a message every 10 seconds in all channels within a namespace
 }
 ```
 
-```php
-$claims = [
-    'sub' => '1234567890',
-    'name' => 'John Doe',
-    'x-ably-capability' => '<...>',
-    'x-ably-clientId' => '<...>',
-    'ably.limits.publish.perAttachment.maxRate.chat1' => 10, // the user can publish 10 messages per second in channel chat1
-    'ably.limits.publish.perAttachment.maxRate.chat:*' => 0.1 // the user can publish a message every 10 seconds in all channels within the chat namespace
-]
-```
-
 ```go
 claims := map[string]interface{}{
   "sub":                   "1234567890",
   "name":                  "John Doe",
   "x-ably-capability":     "<...>",
   "x-ably-clientId":       "<...>",
-  "ably.limits.publish.perAttachment.maxRate.chat1":    10.0, // the user can publish 10 messages per second in channel chat1
-  "ably.limits.publish.perAttachment.maxRate.chat:*": 0.1, // the user can publish a message every 10 seconds in all channels within the chat namespace
+  "ably.limits.publish.perAttachment.maxRate.your-channel":      10.0, // the user can publish 10 messages per second in a specific channel
+  "ably.limits.publish.perAttachment.maxRate.your-namespace:*": 0.1, // the user can publish a message every 10 seconds in all channels within a namespace
 }
 ```
-
-```flutter
-final claims = {
-  'sub': '1234567890',
-  'name': 'John Doe',
-  'x-ably-capability': '<...>', // Replace with actual capability
-  'x-ably-clientId': '<...>', // Replace with actual client ID
-  'ably.limits.publish.perAttachment.maxRate.chat1': 10, // the user can publish 10 messages per second in channel chat1
-  'ably.limits.publish.perAttachment.maxRate.chat:*': 0.1 // the user can publish a message every 10 seconds in all channels within the chat namespace
-};
-```
 </Code>
diff --git a/src/pages/docs/platform/auth/identified-clients.mdx b/src/pages/docs/platform/auth/identified-clients.mdx
new file mode 100644
index 0000000000..e4ba7b8f89
--- /dev/null
+++ b/src/pages/docs/platform/auth/identified-clients.mdx
@@ -0,0 +1,100 @@
+---
+title: Identified clients
+meta_description: "Clients can be allocated a client ID to help control their operations and interactions with Ably channels."
+redirect_from:
+  - /docs/auth/identified-clients
+---
+
+When a client is authenticated and connected to Ably, it is considered to be an authenticated client. While an authenticated client has a means to authenticate with Ably, they do not necessarily have an identity.
+
+When a client is assigned a trusted identity, that is, a `clientId`, then they are considered to be an identified client. For all operations that client performs with the Ably service, their `clientId` field will be automatically populated and can be trusted by other clients.
+
+For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a `clientId` that they are not assigned in their Ably-compatible token. They are unable to masquerade as another `clientId`.
+
+## ClientId immutability <a id="immutability"/>
+
+A connection's `clientId`, once set, is immutable. You cannot change a `clientId` after it has been established for a connection.
+
+### Late initialization
+
+It is possible to have late initialization of `clientId` in certain scenarios:
+
+* AuthCallback discovery: When using `authCallback`, the `clientId` may only become known when the first authCallback completes and returns a token with a `clientId`.
+* Opaque token processing: When the library receives an opaque token string, it only learns the `clientId` when it receives a response from the server that has processed the token.
+
+In both cases, the immutability requirement is satisfied because the `clientId` gets set as part of the client's first interaction with the server. Once this initial authentication is complete, the `clientId` cannot be changed for that connection.
+
+## Assign a clientId <a id="assign"/>
+
+There are three different ways a client can be identified with using a `clientId`:
+
+* A client claims a `clientId` when authenticating with an API key.
+* A client is authenticating with a token issued for a specific `clientId`.
+* A client claims a `clientId` when authenticating with a token that is issued for a wildcard `clientId`.
+
+When a client sets their own ID there is the possibility that they can pretend to be someone else. To prevent this, it is recommended that you embed a `clientId` in the token issued to your clients from your auth server. This ensures that the `clientId` is set by your auth server, and eliminates the chance of a client pretending to be someone else.
+
+<Aside data-type='note'>
+Identifying a client varies depending on whether they are authenticating with basic authentication or token authentication. Token authentication is [recommended](/docs/platform/auth#selecting-auth) in most instances so that clients authenticate using short-lived tokens and do not have access to API keys.
+
+Since you then control the `clientId`, all other clients can rely on the validity of the `clientId` in published messages and of members present in presence channels. This eliminates the possibility of a client pretending to be someone else, as they cannot claim a `clientId` in their own.
+</Aside>
+
+### Basic auth <a id="basic"/>
+
+You can use [basic authentication](/docs/platform/auth/basic) to allow a client to claim any `clientId` when they authenticate with Ably. As the assignation of the `clientId` is not handled by a server, it cannot be trusted to represent the genuine identity of the client.
+
+### Token auth <a id="token"/>
+
+You can use [token authentication](/docs/platform/auth/token) to set an explicit `clientId` when creating or issuing a token. Clients using that token are restricted to operations for only that `clientId`, and all operations will implicitly contain that `clientId`.
+
+For example, when publishing a message, the `clientId` attribute of the message will be pre-populated with that `clientId`. Entering presence will also implicitly use that `clientId`.
+
+#### Using JWT (recommended) <a id="jwt-clientid"/>
+
+The recommended approach is to create a JWT with the `x-ably-clientId` claim. This requires no Ably SDK on your server—any JWT library will work:
+
+<Code>
+```javascript
+const ablyJwt = jwt.sign(
+  {
+    'x-ably-capability': JSON.stringify({ '*': ['*'] }),
+    'x-ably-clientId': userId, // Set the trusted clientId
+  },
+  keySecret,
+  { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+);
+```
+</Code>
+
+See [token authentication scenarios](/docs/platform/auth/token#scenario-standard) for complete server and client examples.
+
+#### Using TokenRequest (alternative) <a id="tokenrequest-clientid"/>
+
+If JWT is not suitable for your use case, you can use the Ably SDK to create a TokenRequest with an explicit `clientId`:
+
+<Code>
+```javascript
+// Server-side with Ably SDK
+const ably = new Ably.Rest(process.env.ABLY_API_KEY);
+const tokenRequest = await ably.auth.createTokenRequest({ clientId: 'user-123' });
+// Return tokenRequest to client
+```
+
+```python
+# Server-side with Ably SDK
+ably = AblyRest(os.environ['ABLY_API_KEY'])
+token_request = await ably.auth.create_token_request({'client_id': 'user-123'})
+# Return token_request to client
+```
+</Code>
+
+See [token authentication](/docs/platform/auth/token#token-request) for complete TokenRequest examples in all languages.
+
+### Wildcard token auth <a id="wildcard"/>
+
+You can use [token authentication](/docs/platform/auth/token) to set a wildcard `clientId` using a value of `*` when creating a token. Clients are then able to assume any identity in their operations, such as when publishing a message or entering presence.
+
+## Unidentified clients <a id="unidentified"/>
+
+If no `clientId` is provided when using [token authentication](/docs/platform/auth/token) then clients are not permitted to assume an identity and will be considered an unidentified client in all operations. Messages published will contain no `clientId` and those clients will not be permitted to enter the [presence](/docs/presence-occupancy/presence) set.
diff --git a/src/pages/docs/platform/auth/index.mdx b/src/pages/docs/platform/auth/index.mdx
new file mode 100644
index 0000000000..6ed83ed957
--- /dev/null
+++ b/src/pages/docs/platform/auth/index.mdx
@@ -0,0 +1,108 @@
+---
+title: Authentication overview
+meta_description: "Ably supports two main authentication schemes: basic authentication and token authentication. Token authentication can be implemented using JWTs, Ably tokens, and Ably token requests."
+redirect_from:
+  - /docs/auth
+  - /docs/rest/authentication
+  - /docs/rest/versions/v1.1/authentication
+  - /docs/rest/versions/v1.0/authentication
+  - /docs/rest/versions/v0.8/authentication
+  - /docs/realtime/authentication
+  - /docs/realtime/versions/v1.1/authentication
+  - /docs/realtime/versions/v1.0/authentication
+  - /docs/realtime/versions/v0.8/authentication
+  - /docs/core-features/authentication
+  - /docs/core-features/versions/v1.1/authentication
+  - /docs/core-features/versions/v1.0/authentication
+  - /docs/core-features/versions/v0.8/authentication
+  - /docs/core-features/authentication.ably-jwt
+  - /docs/general/authentication
+  - /docs/general/_authentication_capabilities
+  - /docs/ids-and-keys
+---
+
+Before a client or server can issue requests to Ably, such as subscribe to channels, or publish messages, it must authenticate with Ably.
+
+## Recommended authentication <a id="recommended"/>
+
+| Environment | Recommended Method | Details |
+|-------------|-------------------|---------|
+| **Client-side** (browsers, mobile apps) | [Token authentication](/docs/platform/auth/token) | Your server creates tokens; clients use `authCallback` to fetch them |
+| **Server-side** (Node.js, Python, etc.) | [Basic authentication](/docs/platform/auth/basic) | Use your API key directly in trusted environments |
+
+<Aside data-type='important'>
+**Never use API keys in client-side code.** API keys don't expire—once compromised, they grant indefinite access. Use [token authentication](/docs/platform/auth/token) with short-lived tokens that can be revoked.
+</Aside>
+
+### Quick start
+
+<Code>
+```javascript
+// Client-side: fetch token from your server
+const realtime = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    const response = await fetch('/api/ably-token');
+    callback(null, await response.text());
+  },
+});
+```
+</Code>
+
+See [token authentication](/docs/platform/auth/token#scenario-standard) for complete server and client examples.
+
+## Authentication terminology <a id="terminology"/>
+
+- **Authentication**: The process of verifying credentials (API key or token) to allow interaction with Ably.
+- **Authorization**: Determining what operations an authenticated client can perform, based on [capabilities](/docs/platform/auth/capabilities).
+- **Identified client**: A client with a verified identity (`clientId`). See [identified clients](/docs/platform/auth/identified-clients).
+
+## Ably API keys <a id="api-keys"/>
+
+Every Ably app can have one or more API keys associated with it. API keys authenticate directly with Ably or issue tokens. Keys can have different [capabilities](/docs/platform/auth/capabilities), and tokens issued from a key can only have a subset of those capabilities.
+
+### API key format <a id="format"/>
+
+An Ably API key string has the following format: `I2E_JQ.OqUdfg:EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0`
+
+The API key has three parts:
+
+1. `I2E_JQ` - the public app ID
+2. `OqUdfg` - the public key ID (`I2E_JQ.OqUdfg` together form the public API key ID)
+3. `EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0` - the API key secret (never share this)
+
+### Create an API key <a id="create"/>
+
+API keys are created in the [Ably dashboard](https://ably.com/dashboard) or programmatically via the [Control API](/docs/platform/account/control-api).
+
+To create an API key in the dashboard:
+
+1. Click the **API Keys** tab in your [dashboard](https://ably.com/dashboard).
+2. Click **Create a new API key**.
+3. Enter a name to identify the key.
+4. Select the [capabilities](/docs/platform/auth/capabilities) to apply.
+5. Optionally enable [token revocation](/docs/platform/auth/revocation).
+6. Optionally restrict scope to specific channels or queues.
+
+<Aside data-type="note">
+Code samples in this documentation use basic authentication for convenience. In production, never use basic authentication client-side as it exposes your API key.
+</Aside>
+
+## Selecting an authentication mechanism <a id="selecting-auth"/>
+
+Ably supports two authentication mechanisms:
+
+1. **[Token authentication](/docs/platform/auth/token)**: Short-lived tokens that expire and can be revoked. Recommended for clients.
+2. **[Basic authentication](/docs/platform/auth/basic)**: Uses your API key directly. Use only on trusted servers.
+
+When deciding which method to use, apply the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege): a client should only possess the credentials and rights it needs. If credentials are compromised, the damage is minimized.
+
+Many applications use a mixed strategy: trusted servers use basic authentication to issue tokens, while browsers and devices use those tokens.
+
+| Scenario | Basic | Token | Recommendation |
+|----------|:-----:|:-----:|----------------|
+| Script may be exposed (browser, mobile) | No | Yes | Use token auth—don't embed API keys in client code |
+| Connection may be insecure | No | Yes | Use token auth to limit exposure window |
+| No server to control access | Yes | No | Basic auth is your only option |
+| Fine-grained access control needed | No | Yes | Token auth allows per-user [capabilities](/docs/platform/auth/capabilities) |
+| Time-limited or revocable access | No | Yes | Tokens expire and can be [revoked](/docs/platform/auth/revocation) |
+| Users must be identified | Partial | Yes | Token auth lets your server set trusted [clientIds](/docs/platform/auth/identified-clients) |
diff --git a/src/pages/docs/auth/revocation.mdx b/src/pages/docs/platform/auth/revocation.mdx
similarity index 97%
rename from src/pages/docs/auth/revocation.mdx
rename to src/pages/docs/platform/auth/revocation.mdx
index dad67730ee..bc98609a21 100644
--- a/src/pages/docs/auth/revocation.mdx
+++ b/src/pages/docs/platform/auth/revocation.mdx
@@ -1,6 +1,8 @@
 ---
 title: Token revocation
 meta_description: "Token revocation is a mechanism that enables an app to invalidate authentication tokens."
+redirect_from:
+  - /docs/auth/revocation
 ---
 
 Token revocation is a mechanism that enables an app to invalidate authentication tokens. This invalidation can be used to force specified clients to re-obtain a token, and subsequently enables the app to modify the rights granted to clients, or to decline to re-issue a token. Token revocation can be enforced immediately or postponed by 30 seconds, allowing the client the opportunity to request a new token (see `allowReauthMargin` under [Revoke a token](#revoke)). By default `allowReauthMargin` is set to false, meaning token revocation is near immediate. Setting this value to true would postpone the revocation by 30 seconds.
@@ -233,7 +235,7 @@ In this example, all users that have been assigned the revocation key `users.gro
 
 ### channel <a id="channel"/>
 
-This target specifier will match tokens that exactly match one of the resource names present in the token [capabilities](/docs/auth/capabilities). Note that this is not the same thing as revoking all tokens that have access to the channel.
+This target specifier will match tokens that exactly match one of the resource names present in the token [capabilities](/docs/platform/auth/capabilities). Note that this is not the same thing as revoking all tokens that have access to the channel.
 
 For example, a token with a capability of `{"foo:*": ["*"]}` will be revoked by a target of `channel:foo:*`, but a revocation to `channel:*:*` will have no effect (even though that is a superset of the capabilities of `foo:*`), and nor will `channel:foo:bar` (even for connections using the token to attach to that particular channel). It must be the exact string used in the token capabilities (which may be inherited from key capabilities).
 
diff --git a/src/pages/docs/auth/token.mdx b/src/pages/docs/platform/auth/token.mdx
similarity index 75%
rename from src/pages/docs/auth/token.mdx
rename to src/pages/docs/platform/auth/token.mdx
index 912d469dfe..e7bf1c7051 100644
--- a/src/pages/docs/auth/token.mdx
+++ b/src/pages/docs/platform/auth/token.mdx
@@ -1,11 +1,23 @@
 ---
 title: "Token auth"
 meta_description: "Token authentication allows clients to authenticate with Ably, without exposing the Ably API key and secret."
+redirect_from:
+  - /docs/auth/token
 ---
 
-Token authentication uses a trusted device with an [API key](/docs/auth#api-key) to issue time-limited tokens to untrusted clients. Tokens have a limited set of access rights, known as [capabilities](/docs/auth/capabilities), and can have a specific [identity](/docs/auth/identified-clients) using a `clientId`.
+Token authentication uses a trusted device with an [API key](/docs/platform/auth#api-key) to issue time-limited tokens to untrusted clients. Tokens have a limited set of access rights, known as [capabilities](/docs/platform/auth/capabilities), and can have a specific [identity](/docs/platform/auth/identified-clients) using a `clientId`.
 
-Token authentication is the recommended authentication method to use client-side as it provides more fine-grained access control and limits the risk of credentials being exposed.
+Token authentication is the recommended authentication method to use client-side for the following reasons:
+
+* Tokens ensure that an Ably API key isn't exposed in client applications.
+* Tokens are short-lived so there is only a short period of time during which a compromised token can be used.
+* Tokens provide more fine-grained access control, which also limits the area of exposure a compromised token can access.
+
+<Aside data-type='note'>
+When selecting an Ably SDK for implementing token authentication with Ably, you don't need to use the realtime interface on the auth server.
+
+As basic authentication is primarily designed for authenticating a secure server, in this situation, and assuming the server is only used for authentication, it is more efficient to use the REST interface, as the overhead associated with maintaining a realtime connection, is not required to issue tokens.
+</Aside>
 
 ## Access restrictions <a id="restrictions"/>
 
@@ -35,6 +47,49 @@ Providing a literal `token` or `tokenDetails` is typically used for testing: sin
 
 Authentication using tokens can be achieved requesting and issuing [Ably Tokens](#tokens) or passing a [JSON Web Tokens (JWT)](#jwt) to the Ably service.
 
+## Choosing a token mechanism <a id="choosing"/>
+
+Ably supports three token authentication mechanisms. **Ably JWT is recommended for most use cases** as it offers the best combination of flexibility, performance, and features.
+
+### Ably JWT (recommended) <a id="choosing-jwt"/>
+
+Best for most applications. Your server creates a JWT signed with your Ably API key—no SDK required. Supports channel-scoped claims and per-connection rate limits.
+
+See [implementation details](#standard).
+
+### TokenRequest <a id="choosing-tokenrequest"/>
+
+Your server creates a signed `TokenRequest` using the Ably SDK. The client exchanges this with Ably for an actual token. Choose when your capability list is very large, or you need to keep capabilities confidential.
+
+See [implementation details](#token-request).
+
+### Embedded Token JWT <a id="choosing-embedded"/>
+
+Wrap an Ably token inside your existing JWT structure for deep integration with existing auth systems.
+
+See [implementation details](#embedded).
+
+## Token mechanism comparison <a id="comparison"/>
+
+| Feature | Ably JWT (Recommended) | Embedded JWT | TokenRequest |
+|---------|:----------------------:|:------------:|:------------:|
+| **Server SDK required** | No | Yes | Yes |
+| **Client round-trip to Ably** | No | No | Yes |
+| **Channel-scoped claims** | Yes | No | No |
+| **Per-connection rate limits** | Yes | No | No |
+| Works with any MQTT client | Yes | Yes | Yes |
+| Automatic SDK token refresh | Yes | Yes | Yes |
+| Implementation complexity | Medium | Higher | Low |
+| Works in serverless/edge | Yes (stateless) | Yes (with SDK) | Yes (with SDK) |
+
+<Aside data-type='important'>
+**JWT-only features you lose with other token methods:**
+- Channel-scoped user claims (`ably.channel.*`) - trusted metadata other clients can read
+- Per-connection publish rate limits (`ably.limits.publish.*`) - restrict message rates per connection
+
+If you use TokenRequest or Embedded JWT, you will **not** have access to these features.
+</Aside>
+
 ## Token refresh <a id="refresh"/>
 
 One of the important benefits of using an Ably SDK is that the automatic refresh of tokens will be handled for you.
@@ -45,14 +100,13 @@ To use automatic refresh of tokens, provide either an `authUrl` or an `authCallb
 
 Understanding how token authentication works helps clarify why automatic renewal is essential:
 
-1. Your server uses the Ably API key to request a 'Token Request' object from Ably.
-2. Your client uses this 'Token Request' object to request the actual token from the Ably server every time it needs to authenticate.
-3. These tokens are short-lived and expire after a certain period of time.
-4. The client SDK automatically requests a new token just before the previous one expires, ensuring the connection never drops due to authentication failure.
+1. Your client calls `authUrl` or `authCallback` to request a token from your server.
+2. Your server validates the client and returns a token (JWT or TokenRequest).
+3. The client uses this token to authenticate with Ably.
+4. Tokens are short-lived and expire after a set period.
+5. The client SDK automatically requests a new token before expiry, ensuring uninterrupted connectivity.
 
-Using an `authUrl` or `authCallback` ensures your client automatically requests a new token when needed, making the authentication process seamless and preventing service interruptions.
-
-An `authURL` is recommended for use with web-based clients as they can easily utilize cookies and other web-only features. For non-web clients, `authCallback` is the recommended strategy.
+An `authURL` is recommended for web-based clients as they can utilize cookies. For non-web clients, `authCallback` is the recommended strategy.
 
 ### Token TTL limits
 
@@ -60,7 +114,7 @@ Ably enforces maximum TTL (time-to-live) limits on different types of tokens:
 
 - Access tokens: Maximum TTL of 24 hours.
 - Device tokens (for push notifications): Maximum TTL of 5 years.
-- Revocable tokens: Maximum TTL of 1 hour (when [token revocation](/docs/auth/revocation#revocable-tokens) is enabled).
+- Revocable tokens: Maximum TTL of 1 hour (when [token revocation](/docs/platform/auth/revocation#revocable-tokens) is enabled).
 
 <Aside data-type="important">
 Attempting to create a token with a TTL that exceeds these limits will result in an error code [40003](/docs/platform/errors/codes#40003).
@@ -180,185 +234,54 @@ The client will obtain a token, JWT, or tokenRequest from the URL and use it to
 
 ### authCallback <a id="auth-callback"/>
 
-You can specify an authentication callback function when you create the Ably client. Inside `authCallback`, you can make a network request to your servers to generate the `tokenRequest`. For example:
+You can specify an authentication callback function when you create the Ably client. Inside `authCallback`, you make a network request to your server to obtain a JWT. **Returning a JWT string is recommended** as it provides the best combination of security and features.
 
 <Code>
 ```realtime_javascript
-const ablyClient = new Realtime({
-    authCallback: async (tokenParams, callback) => {
-        let tokenRequest;
-        try {
-            tokenRequest = await obtainTokenRequest(); // Make a network request to your server
-        } catch (err) {
-            callback(err, null);
-            return;
-        }
-        callback(null, tokenRequest);
-    }
-});
-```
-
-```realtime_nodejs
-const ablyClient = new Realtime({
-    authCallback: async (tokenParams, callback) => {
-        let tokenRequest;
-        try {
-            tokenRequest = await obtainTokenRequest(); // Make a network request to your server
-        } catch (err) {
-            callback(err, null);
-            return;
-        }
-        callback(null, tokenRequest);
+const realtime = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token', {
+        credentials: 'include',
+      });
+      if (!response.ok) throw new Error('Auth failed');
+      callback(null, await response.text());
+    } catch (error) {
+      callback(error, null);
     }
+  },
 });
 ```
 
 ```realtime_python
-realtime = AblyRealtime(auth_callback=get_token_request)
-
-async def get_token_request(*args, **kwargs):
-    create_token_request = await get_token_request() // Implement this function to get a token request from your server
-
-    if create_token_request.status_code == 200:
-        token_request = create_token_request.json()
-
-        return token_request
-    else:
-        raise Exception(f"Failed to retrieve token request: {create_token_request.status_code} - {create_token_request.text}")
-```
-
-```realtime_go
-realtime, _ := ably.NewRealtime(
-  ably.WithAuthCallback(func(context.Context, ably.TokenParams) (ably.Tokener, error) {
-    createTokenRequest := getTokenRequest() // Implement this function to get a token request from your server
+import aiohttp
 
-    if (createTokenRequest.StatusCode == 200) {
-      return createTokenRequest
-    }
-
-    return "Failed to retrieve token request: '%v' - '%v'", createTokenRequest.StatusCode, createTokenRequest.Text
-  })
-)
-```
-
-```realtime_flutter
-ably.ClientOptions clientOptions = ably.ClientOptions(
-    authCallback: (ably.TokenParams tokenParams) async {
-      // `createTokenRequest` should be implemented to communicate with user server
-      ably.TokenRequest tokenRequest = await createTokenRequest(tokenParams);
-      // `authCallback` has to return an instance of TokenRequest
-      return tokenRequest;
-    }
-);
+async def get_ably_jwt(*args, **kwargs):
+    async with aiohttp.ClientSession() as session:
+        async with session.get('/api/ably-token') as response:
+            if response.status != 200:
+                raise Exception(f"Auth failed: {response.status}")
+            return await response.text()
 
-ably.Realtime realtime = ably.Realtime(options: clientOptions);
+realtime = AblyRealtime(auth_callback=get_ably_jwt)
 ```
 
 ```realtime_java
 ClientOptions options = new ClientOptions();
-
 options.authCallback = new Auth.TokenCallback() {
     @Override
     public Object getTokenRequest(Auth.TokenParams params) throws AblyException {
-        // Implement this function to get a token request from your server
-        return getTokenRequestFromServer();
+        // Make HTTP request to your auth server and return JWT string
+        return fetchJwtFromServer();
     }
 };
-
 AblyRealtime realtime = new AblyRealtime(options);
 ```
-
-```rest_javascript
-const rest = new Ably.Rest({
-  authCallback: (tokenParams, callback) => {
-    // implement your callback here
-  },
-});
-```
-
-```rest_nodejs
-const rest = new Ably.Rest({
-  authCallback: (tokenParams, callback) => {
-    // implement your callback here
-  },
-});
-```
-
-```rest_python
-rest = AblyRest(auth_callback=get_token_request)
-
-async def get_token_request(*args, **kwargs):
-    create_token_request = await get_token_request() // Implement this function to get a token request from your server
-
-    if create_token_request.status_code == 200:
-        token_request = create_token_request.json()
-
-        return token_request
-    else:
-        raise Exception(f"Failed to retrieve token request: {create_token_request.status_code} - {create_token_request.text}")
-```
-
-```rest_java
-ClientOptions options = new ClientOptions();
-
-options.authCallback = new Auth.TokenCallback() {
-    @Override
-    public Object getTokenRequest(Auth.TokenParams params) throws AblyException {
-        // Implement this function to get a token request from your server
-        return getTokenRequestFromServer();
-    }
-};
-
-AblyRest rest = new AblyRest(options);
-```
-
-```rest_php
-$rest = new Ably\AblyRest(
-    [
-        'authCallback' => function(Ably\Models\TokenParams $params) {
-            $curl = curl_init('/auth');
-            curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
-            $response = curl_exec($curl);
-            curl_close($curl);
-
-            $tokenRequestData = json_decode($response, true);
-            $tokenRequest = new Ably\Models\TokenRequest($tokenRequestData);
-
-            return $tokenRequest;
-        }
-    ]
-);
-```
-
-```rest_go
-rest, _ := ably.NewREST(
-  ably.WithAuthCallback(func(context.Context, ably.TokenParams) (ably.Tokener, error) {
-    createTokenRequest := getTokenRequest() // Implement this function to get a token request from your server
-
-    if (createTokenRequest.StatusCode == 200) {
-      return createTokenRequest
-    }
-
-    return "Failed to retrieve token request: '%v' - '%v'", createTokenRequest.StatusCode, createTokenRequest.Text
-  })
-)
-```
-
-```rest_flutter
-ably.ClientOptions clientOptions = ably.ClientOptions(
-    authCallback: (ably.TokenParams tokenParams) async {
-      // `createTokenRequest` should be implemented to communicate with user server
-      ably.TokenRequest tokenRequest = await createTokenRequest(tokenParams);
-      // `authCallback` has to return an instance of TokenRequest
-      return tokenRequest;
-    }
-);
-
-ably.Rest rest = ably.Rest(options: clientOptions);
-```
 </Code>
 
-The [`tokenParams`](/docs/api/realtime-sdk/authentication#token-params) argument in `authCallback` is available for convenience, allowing you to see the capabilities, `clientId`, and other details requested by the client. However, `tokenParams` should not be trusted or used to generate the `tokenRequest` on the server side. Instead it is recommended that your `createTokenRequest` API authenticates clients separately, for example based on cookies, headers, or HTTP body.
+For complete client and server examples, see [Common architectural scenarios](#scenarios).
+
+The [`tokenParams`](/docs/api/realtime-sdk/authentication#token-params) argument in `authCallback` is available for convenience, allowing you to see the capabilities, `clientId`, and other details requested by the client. However, `tokenParams` should not be trusted or used to generate tokens on the server side. Your auth endpoint should authenticate clients separately using cookies, headers, or request body.
 
 ## AuthOptions <a id="auth-options"/>
 
@@ -524,167 +447,6 @@ AblyRest rest = new AblyRest(options);
 ```
 </Code>
 
-## Ably Tokens <a id="tokens"/>
-
-Ably Tokens can be used to authenticate with Ably in the following ways:
-
-* Ably [TokenRequest](#token-request) is created by your servers and passed to clients.
-* An [Ably Token](#ably-token) is issued by your servers and passed to clients.
-
-Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).
-
-### Ably TokenRequest <a id="token-request"/>
-
-Using an Ably SDK, a `TokenRequest` is [generated from your server](/docs/api/realtime-sdk/authentication#create-token-request) and returned to the client-side SDK instance. The client-side SDK instance then uses the [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) to request an [Ably Token](/docs/api/realtime-sdk/authentication#request-token) from Ably, and subsequently authenticates using that [Ably Token](/docs/api/realtime-sdk/authentication#token-details).
-
-This is the recommended approach for client-side authentication, for the following reasons:
-
-* An Ably `TokenRequest` can be generated securely by your servers without communicating with Ably.
-* Your secret API key is never shared with Ably or your clients.
-* An Ably `TokenRequest` cannot be tampered with due to being signed, must be used soon after creation, and can only be used once.
-
-The process used by Ably SDKs to authenticate with Ably using a `TokenRequest` is illustrated in the following diagram:
-
-![Ably TokenRequest auth process diagram](../../../images/content/diagrams/Ably-token-auth-1.png)
-
-The following is an example of creating an Ably `TokenRequest`:
-
-<Code>
-```javascript
-const ably = new Ably.Rest({ key: '{{API_KEY}}' });
-const tokenRequest = await ably.auth.createTokenRequest({ clientId: 'client@example.com' });
-```
-
-```python
-ably = AblyRest('{{API_KEY}}')
-token = await ably.auth.create_token_request(
-{
-    "clientId": "client@example.com",
-    "capability": {
-        "channel1": ["publish", "subscribe"],
-    },
-    'ttl': 3600 * 1000, # ms
-})
-```
-
-```java
-ClientOptions options = new ClientOptions("{{API_KEY}}");
-AblyRest rest = new AblyRest(options);
-
-Auth.TokenParams tokenParams = new Auth.TokenParams();
-tokenParams.clientId = "client@example.com";
-
-Auth.TokenRequest tokenDetails = rest.auth.createTokenRequest(tokenParams, null);
-```
-
-```php
-$rest = new Ably\AblyRest(
-    ['key' => '{{API_KEY}}']
-);
-
-$tokenRequest = $rest->auth->createTokenRequest(
-    ['clientId' => 'client@example.com']
-);
-```
-
-```go
-rest, err := ably.NewREST(
-  ably.WithKey("{{API_KEY}}"))
-if err != nil {
-  log.Fatalf("Error creating Ably client: %v", err)
-}
-
-tokenParams := &ably.TokenParams{ClientID: "client@example.com"}
-tokenRequest, _ := rest.Auth.CreateTokenRequest(tokenParams)
-```
-
-```flutter
-final clientOptions = ably.ClientOptions(
-  key: '{{API_KEY}}',
-);
-final rest = ably.Rest(options: clientOptions);
-const tokenParams = ably.TokenParams(
-  clientId: 'client@example.com'
-);
-final tokenRequest = rest.auth.createTokenRequest(tokenParams: tokenParams);
-```
-</Code>
-
-Clients can pass this server-side generated `TokenRequest` to Ably to authenticate with Ably automatically.
-
-### Ably Token <a id="ably-token"/>
-
-Using an Ably SDK, an Ably Token is [requested by your servers](/docs/api/realtime-sdk/authentication#request-token) from Ably and then passed to the client-side SDK instance. The client-side SDK instance then uses that [Ably Token](/docs/api/realtime-sdk/authentication#tokens) to authenticate with Ably. This is an alternative approach for authentication that enables you to issue"Ably Tokens directly as opposed to providing Ably `TokenRequests` from your servers.
-
-The advantage for clients is that it saves one round trip request as they do not need to request an Ably Token themselves. The disadvantage is that your servers must communicate with Ably each time an Ably Token is required.
-
-The process used by Ably SDKs to authenticate with Ably using an Ably Token is illustrated in the following diagram:
-
-![Ably token auth process diagram](../../../images/content/diagrams/Ably-Auth-Overview1.png)
-
-The following is an example of issuing an Ably Token from a server:
-
-<Code>
-```javascript
-const ably = new Ably.Rest({ key: '{{API_KEY}}' });
-const tokenDetails = await ably.auth.requestToken({ clientId: 'client@example.com' });
-```
-
-```python
-rest = AblyRest(key='{{API_KEY}}')
-token_request_params = {
-    'clientId': 'client@example.com',
-}
-
-token_details = await rest.auth.request_token(token_params=token_request_params)
-```
-
-```java
-ClientOptions options = new ClientOptions("{{API_KEY}}");
-AblyRest rest = new AblyRest(options);
-
-Auth.TokenParams tokenParams = new Auth.TokenParams();
-tokenParams.clientId = "client@example.com";
-
-Auth.TokenDetails tokenDetails = rest.auth.requestToken(tokenParams, null);
-```
-
-```php
-$rest = new Ably\AblyRest(
-    ['key' => '{{API_KEY}}']
-);
-
-$tokenDetails = $rest->auth->requestToken(
-    ['clientId' => 'client@example.com']
-);
-```
-
-```go
-rest, err := ably.NewREST(
-  ably.WithKey("API_KEY"))
-if err != nil {
-  log.Fatalf("Error creating Ably client: %v", err)
-}
-
-tokenParams := &ably.TokenParams{ClientID: "client@example.com"}
-tokenRequest, _ := rest.Auth.RequestToken(context.Background(), tokenParams)
-```
-
-```flutter
-final clientOptions = ably.ClientOptions(
-  key: '{{API_KEY}}',
-);
-final rest = ably.Rest(options: clientOptions);
-
-const tokenParams = ably.TokenParams(
-  clientId: 'client@example.com',
-);
-final tokenDetails = await rest.auth.requestToken(
-    tokenParams: tokenParams
-);
-```
-</Code>
-
 ## JSON Web Tokens (JWT) <a id="jwt"/>
 
 JSON Web Tokens (JWT) can be used to authenticate with Ably in the following ways:
@@ -692,11 +454,9 @@ JSON Web Tokens (JWT) can be used to authenticate with Ably in the following way
 * [Ably JWT](#standard) is created by your servers and passed to clients.
 * [Ably Token](#embedded) is embedded in a JWT from your server and passed to clients.
 
-Note that the machine on which you are running your auth server should have an accurate clock, as tokens contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).
-
 ### JWT using your API key <a id="standard"/>
 
-It is possible to use a [JWT](https://jwt.io) as a form of token for authentication with Ably, so long as it is structured appropriately, in what will be referred to as an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). It is possible for an Ably JWT to contain claims indicating its `clientId`, capabilities and expiry - in an analogous way to an [Ably Token](#tokens) - and it is signed with the applicable [Ably API key's secret part](/docs/auth#api-key).
+It is possible to use a [JWT](https://jwt.io) as a form of token for authentication with Ably, so long as it is structured appropriately, in what will be referred to as an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). It is possible for an Ably JWT to contain claims indicating its `clientId`, capabilities and expiry - in an analogous way to an [Ably Token](#tokens) - and it is signed with the applicable [Ably API key's secret part](/docs/platform/auth#api-key).
 
 This is similar to signing an Ably [`TokenRequest`](#token-request), but the client does not need to request an Ably Token, instead being able to use the Ably JWT as a token in itself. Any compliant third-party JWT library may be used to create the JWT without requiring the token to be issued by Ably. This can be useful for situations where an Ably client library is not available, such as an embedded device connecting to Ably via [MQTT](/docs/protocols/mqtt).
 
@@ -1082,9 +842,388 @@ final ablyJwt = "$base64Header.$base64Claims.$signature";
 ```
 </Code>
 
+## Ably Tokens <a id="tokens"/>
+
+Ably Tokens can be used to authenticate with Ably in the following ways:
+
+* Ably [TokenRequest](#token-request) is created by your servers and passed to clients.
+* An [Ably Token](#ably-token) is issued by your servers and passed to clients.
+
+Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).
+
+### Ably TokenRequest <a id="token-request"/>
+
+Using an Ably SDK, a `TokenRequest` is [generated from your server](/docs/api/realtime-sdk/authentication#create-token-request) and returned to the client-side SDK instance. The client-side SDK instance then uses the [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) to request an [Ably Token](/docs/api/realtime-sdk/authentication#request-token) from Ably, and subsequently authenticates using that [Ably Token](/docs/api/realtime-sdk/authentication#token-details).
+
+TokenRequest is an alternative to JWT when you need to keep capabilities confidential or when your capability list is very large. Key characteristics:
+
+* A `TokenRequest` can be generated securely by your servers without communicating with Ably.
+* Your secret API key is never shared with Ably or your clients.
+* A `TokenRequest` cannot be tampered with due to being signed, must be used soon after creation, and can only be used once.
+
+The process used by Ably SDKs to authenticate with Ably using a `TokenRequest` is illustrated in the following diagram:
+
+![Ably TokenRequest auth process diagram](../../../images/content/diagrams/Ably-token-auth-1.png)
+
+The following is an example of creating an Ably `TokenRequest`:
+
+<Code>
+```javascript
+const ably = new Ably.Rest({ key: '{{API_KEY}}' });
+const tokenRequest = await ably.auth.createTokenRequest({ clientId: 'client@example.com' });
+```
+
+```python
+ably = AblyRest('{{API_KEY}}')
+token = await ably.auth.create_token_request(
+{
+    "clientId": "client@example.com",
+    "capability": {
+        "your-channel": ["publish", "subscribe"],
+    },
+    'ttl': 3600 * 1000, # ms
+})
+```
+
+```java
+ClientOptions options = new ClientOptions("{{API_KEY}}");
+AblyRest rest = new AblyRest(options);
+
+Auth.TokenParams tokenParams = new Auth.TokenParams();
+tokenParams.clientId = "client@example.com";
+
+Auth.TokenRequest tokenDetails = rest.auth.createTokenRequest(tokenParams, null);
+```
+
+```php
+$rest = new Ably\AblyRest(
+    ['key' => '{{API_KEY}}']
+);
+
+$tokenRequest = $rest->auth->createTokenRequest(
+    ['clientId' => 'client@example.com']
+);
+```
+
+```go
+rest, err := ably.NewREST(
+  ably.WithKey("{{API_KEY}}"))
+if err != nil {
+  log.Fatalf("Error creating Ably client: %v", err)
+}
+
+tokenParams := &ably.TokenParams{ClientID: "client@example.com"}
+tokenRequest, _ := rest.Auth.CreateTokenRequest(tokenParams)
+```
+
+```flutter
+final clientOptions = ably.ClientOptions(
+  key: '{{API_KEY}}',
+);
+final rest = ably.Rest(options: clientOptions);
+const tokenParams = ably.TokenParams(
+  clientId: 'client@example.com'
+);
+final tokenRequest = rest.auth.createTokenRequest(tokenParams: tokenParams);
+```
+</Code>
+
+Clients can pass this server-side generated `TokenRequest` to Ably to authenticate with Ably automatically.
+
+### Ably Token <a id="ably-token"/>
+
+Using an Ably SDK, an Ably Token is [requested by your servers](/docs/api/realtime-sdk/authentication#request-token) from Ably and then passed to the client-side SDK instance. The client-side SDK instance then uses that [Ably Token](/docs/api/realtime-sdk/authentication#tokens) to authenticate with Ably. This is an alternative approach for authentication that enables you to issue Ably Tokens directly as opposed to providing Ably `TokenRequests` from your servers.
+
+The advantage for clients is that it saves one round trip request as they do not need to request an Ably Token themselves. The disadvantage is that your servers must communicate with Ably each time an Ably Token is required.
+
+The process used by Ably SDKs to authenticate with Ably using an Ably Token is illustrated in the following diagram:
+
+![Ably token auth process diagram](../../../images/content/diagrams/Ably-Auth-Overview1.png)
+
+The following is an example of issuing an Ably Token from a server:
+
+<Code>
+```javascript
+const ably = new Ably.Rest({ key: '{{API_KEY}}' });
+const tokenDetails = await ably.auth.requestToken({ clientId: 'client@example.com' });
+```
+
+```python
+rest = AblyRest(key='{{API_KEY}}')
+token_request_params = {
+    'clientId': 'client@example.com',
+}
+
+token_details = await rest.auth.request_token(token_params=token_request_params)
+```
+
+```java
+ClientOptions options = new ClientOptions("{{API_KEY}}");
+AblyRest rest = new AblyRest(options);
+
+Auth.TokenParams tokenParams = new Auth.TokenParams();
+tokenParams.clientId = "client@example.com";
+
+Auth.TokenDetails tokenDetails = rest.auth.requestToken(tokenParams, null);
+```
+
+```php
+$rest = new Ably\AblyRest(
+    ['key' => '{{API_KEY}}']
+);
+
+$tokenDetails = $rest->auth->requestToken(
+    ['clientId' => 'client@example.com']
+);
+```
+
+```go
+rest, err := ably.NewREST(
+  ably.WithKey("API_KEY"))
+if err != nil {
+  log.Fatalf("Error creating Ably client: %v", err)
+}
+
+tokenParams := &ably.TokenParams{ClientID: "client@example.com"}
+tokenRequest, _ := rest.Auth.RequestToken(context.Background(), tokenParams)
+```
+
+```flutter
+final clientOptions = ably.ClientOptions(
+  key: '{{API_KEY}}',
+);
+final rest = ably.Rest(options: clientOptions);
+
+const tokenParams = ably.TokenParams(
+  clientId: 'client@example.com',
+);
+final tokenDetails = await rest.auth.requestToken(
+    tokenParams: tokenParams
+);
+```
+</Code>
+
+## Common architectural scenarios <a id="scenarios"/>
+
+### Standard application <a id="scenario-standard"/>
+
+For web and mobile applications, create an endpoint that validates users and returns Ably JWTs. This works with any authentication system—sessions, JWT middleware (Auth0, Firebase, Cognito), or custom auth.
+
+**Server (no Ably SDK required):**
+
+<Code>
+```rest_nodejs
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+app.get('/api/ably-token', async (req, res) => {
+  // Validate user with your auth system (session, JWT middleware, etc.)
+  const userId = req.user?.id || req.session?.userId;
+  if (!userId) {
+    return res.status(401).json({ error: 'Not authenticated' });
+  }
+
+  const ablyJwt = jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({
+        '*': ['publish', 'subscribe', 'presence'],
+      }),
+      'x-ably-clientId': userId,
+    },
+    keySecret,
+    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+  );
+
+  res.send(ablyJwt);
+});
+```
+
+```rest_python
+from flask import Flask, request, session
+import jwt
+import os
+import json
+import time
+
+app = Flask(__name__)
+api_key = os.environ['ABLY_API_KEY']
+key_name, key_secret = api_key.split(':')
+
+@app.route('/api/ably-token')
+def get_token():
+    # Validate user with your auth system
+    user_id = getattr(request, 'user', {}).get('id') or session.get('user_id')
+    if not user_id:
+        return {'error': 'Not authenticated'}, 401
+
+    now = int(time.time())
+    ably_jwt = jwt.encode(
+        {
+            'iat': now,
+            'exp': now + 3600,
+            'x-ably-capability': json.dumps({
+                '*': ['publish', 'subscribe', 'presence'],
+            }),
+            'x-ably-clientId': user_id,
+        },
+        key_secret,
+        algorithm='HS256',
+        headers={'kid': key_name}
+    )
+
+    return ably_jwt
+```
+</Code>
+
+**Client:**
+
+<Code>
+```realtime_javascript
+const realtime = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token');
+      const token = await response.text();
+      callback(null, token);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
+```
+</Code>
+
+### IoT and serverless <a id="scenario-serverless"/>
+
+For IoT devices and serverless functions, JWT is ideal because it requires no SDK and is stateless:
+
+**Serverless function (AWS Lambda, Cloud Functions):**
+
+<Code>
+```rest_nodejs
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+export const handler = async (event) => {
+  const userId = event.requestContext.authorizer.claims.sub;
+
+  const ablyJwt = jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({ '*': ['*'] }),
+      'x-ably-clientId': userId,
+    },
+    keySecret,
+    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+  );
+
+  return { statusCode: 200, body: ablyJwt };
+};
+```
+</Code>
+
+**IoT device provisioning:**
+
+<Code>
+```rest_python
+import jwt
+import time
+import json
+import os
+
+def create_device_jwt(device_id: str) -> str:
+    api_key = os.environ['ABLY_API_KEY']
+    key_name, key_secret = api_key.split(':')
+
+    now = int(time.time())
+    return jwt.encode(
+        {
+            'iat': now,
+            'exp': now + 86400,  # 24 hours
+            'x-ably-capability': json.dumps({
+                f'devices:{device_id}': ['publish'],
+                'control': ['subscribe'],
+            }),
+            'x-ably-clientId': device_id,
+        },
+        key_secret,
+        algorithm='HS256',
+        headers={'kid': key_name}
+    )
+```
+</Code>
+
+Devices can use this JWT with any MQTT client. See [MQTT with JWT authentication](/docs/protocols/mqtt#jwt-auth) for examples.
+
+### Multi-tenant SaaS with user roles <a id="scenario-multitenant"/>
+
+**Recommendation: Ably JWT with channel claims**
+
+When you need to pass trusted user metadata (roles, permissions) to channels:
+
+**Server:**
+
+<Code>
+```rest_nodejs
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+function createTenantJwt(userId, tenantId, role) {
+  return jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({
+        [`tenant:${tenantId}:*`]: ['publish', 'subscribe', 'presence'],
+      }),
+      'x-ably-clientId': userId,
+      // Channel-scoped claims - JWT only feature
+      [`ably.channel.tenant:${tenantId}:chat`]: JSON.stringify({
+        role: role,
+        permissions: role === 'admin' ? ['moderate', 'delete'] : ['read'],
+      }),
+    },
+    keySecret,
+    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+  );
+}
+```
+</Code>
+
+Other clients can read these trusted claims from presence or message metadata.
+
+### Rate-limited publishing <a id="scenario-ratelimit"/>
+
+**Recommendation: Ably JWT with rate limits**
+
+When you need to restrict how fast specific clients can publish:
+
+**Server:**
+
+<Code>
+```rest_nodejs
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+function createRateLimitedJwt(userId) {
+  return jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({ '*': ['publish', 'subscribe'] }),
+      'x-ably-clientId': userId,
+      // Per-connection rate limit - JWT only feature
+      'ably.limits.publish.perAttachment.maxRate.*': 10, // 10 msgs/sec max on all channels
+    },
+    keySecret,
+    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+  );
+}
+```
+</Code>
+
 ## Dynamic channel access control <a id="dynamic-access"/>
 
-Token authentication allows you to dynamically change a client's channel access permissions without disconnecting. Use the [`authorize()`](/docs/api/realtime-sdk/authentication#authorize) method to re-authenticate with updated [capabilities](/docs/auth/capabilities).
+Token authentication allows you to dynamically change a client's channel access permissions without disconnecting. Use the [`authorize()`](/docs/api/realtime-sdk/authentication#authorize) method to re-authenticate with updated [capabilities](/docs/platform/auth/capabilities).
 
 When you call `client.auth.authorize()`:
 
@@ -1119,22 +1258,8 @@ try {
 
 For security purposes, handle non-compliant clients by:
 - Set shorter token TTL expiry times to force frequent re-authentication (minimum 10 minutes recommended).
-- Use the [token revocation API](/docs/auth/revocation) to immediately invalidate tokens.
+- Use the [token revocation API](/docs/platform/auth/revocation) to immediately invalidate tokens.
 
 <Aside data-type="important">
 The `authorize()` method maintains the existing connection while updating permissions, making it ideal for real-time applications where connection continuity is important.
 </Aside>
-
-## When to use token auth <a id="when"/>
-
-Ably recommends that token authentication is used client-side for the following reasons:
-
-* Tokens ensure that an Ably API key isn't exposed in client applications.
-* Tokens are short-lived so there is only a short period of time during which a compromised token can be used.
-* Tokens provide more fine-grained access control, which also limits the area of exposure a compromised token can access.
-
-<Aside data-type='note'>
-When selecting an Ably SDK for implementing token authentication with Ably, you don't need to use the realtime interface on the auth server.
-
-As basic authentication is primarily designed for authenticating a secure server, in this situation, and assuming the server is only used for authentication, it is more efficient to use the REST interface, as the overhead associated with maintaining a realtime connection, is not required to issue tokens.
-</Aside>
diff --git a/src/pages/docs/platform/errors/codes.mdx b/src/pages/docs/platform/errors/codes.mdx
index 538ae2279e..97f0784aa7 100644
--- a/src/pages/docs/platform/errors/codes.mdx
+++ b/src/pages/docs/platform/errors/codes.mdx
@@ -48,11 +48,11 @@ Additional examples of the `40003` error code output include:
 * **40003: Excessive value for TTL**
 This error occurs when the [TTL](/docs/api/rest-sdk/authentication#token-request) set for a token parameter exceeds the maximum allowed value of 24 hours.
 * **40003: Excessive value for TTL (revocation is enabled on this key)**
-This error occurs when [revocation](/docs/auth/revocation#revocable-tokens) is enabled, revocable tokens are limited to a TTL of 1 hour instead of 24 hours.
+This error occurs when [revocation](/docs/platform/auth/revocation#revocable-tokens) is enabled, revocable tokens are limited to a TTL of 1 hour instead of 24 hours.
 
 ## 40005: Invalid credentials <a id="40005"/>
 
-This error occurs when the [API key](/docs/auth#api-keys) or [token](/docs/auth/token) used to initialize the library is invalid.
+This error occurs when the [API key](/docs/platform/auth#api-keys) or [token](/docs/platform/auth/token) used to initialize the library is invalid.
 Resolution: The following steps can help resolve this issue:
 
 * API key initialization:
@@ -60,7 +60,7 @@ Resolution: The following steps can help resolve this issue:
 ** In your [Ably dashboard](https://ably.com/accounts/any) to the **API keys** tab.
 ** Use one of these API keys instead of your current one or create a [new API key](/docs/platform/account/app/api#create) with the necessary permissions and privileges and use that to instance the SDK.
 * Token initialization:
-**  If you are using [token authentication](/docs/auth/token), ensure you are correctly requesting a valid token before using it with Ably.
+**  If you are using [token authentication](/docs/platform/auth/token), ensure you are correctly requesting a valid token before using it with Ably.
 
 ## 40006: Invalid connectionId <a id="40006"/>
 
@@ -85,11 +85,11 @@ This error occurs when using the channel [enumeration](/docs/api/rest-api#enumer
 
 ## 40012: Invalid `clientId` <a id="40012"/>
 
-This error occurs when a `clientId` is invalid due to disallowed characters or a mismatch between the `clientId` specified in the request and the one assigned in the authentication [token](/docs/auth/token).
+This error occurs when a `clientId` is invalid due to disallowed characters or a mismatch between the `clientId` specified in the request and the one assigned in the authentication [token](/docs/platform/auth/token).
 
 Examples of this error are when:
 
-* The client attempts to use `*` as a `clientId`, which is not allowed because `*` is used as a [wildcard](/docs/auth/capabilities#wildcards) in capability expressions.
+* The client attempts to use `*` as a `clientId`, which is not allowed because `*` is used as a [wildcard](/docs/platform/auth/capabilities#wildcards) in capability expressions.
 * A client tries to assume an ID of `foo` for an operation, but the token they are using specifies an ID of `bar`.
 
 ## 40013: Invalid message data or encoding <a id="40013"/>
@@ -143,7 +143,7 @@ Examples of this error include attempting to create a resource that already exis
 
 Resolution: The following steps can help resolve this issue:
 * Ensure that an app with the requested name does not already exist in your account. If it does, use a different name.
-* Verify that the [capabilities](/docs/auth/capabilities#capability-operations) listed in the request are valid when creating an API key.
+* Verify that the [capabilities](/docs/platform/auth/capabilities#capability-operations) listed in the request are valid when creating an API key.
 
 ## 40023: Action requires a newer protocol version <a id="40023"/>
 
@@ -179,11 +179,11 @@ const extras = {
 
 ## 40100: Unauthorized <a id="40100"/>
 
-This error occurs when an action cannot be performed due to a lack of [authentication](/docs/auth). There will be additional info in the `message` property about the reason the action could not be performed.
+This error occurs when an action cannot be performed due to a lack of [authentication](/docs/platform/auth). There will be additional info in the `message` property about the reason the action could not be performed.
 
 ## 40101: Invalid credentials <a id="40101"/>
 
-This error occurs when [authentication](/docs/auth) credentials are invalid. The specific error message may provide further details about the cause.
+This error occurs when [authentication](/docs/platform/auth) credentials are invalid. The specific error message may provide further details about the cause.
 
 An example of this error is when a signed token request is invalid due to a mismatched cryptographic signature (MAC does not match) or when the `clientId` specified in the Ably SDK does not match the `clientId` in the access token.
 
@@ -205,7 +205,7 @@ Resolution: Review your authentication setup and token request implementation. E
 
 ## 40102: Incompatible credentials <a id="40102"/>
 
-This error occurs when [authentication](/docs/auth) credentials do not match the existing connection, causing the connection to enter the [failed state](/docs/connect/states).
+This error occurs when [authentication](/docs/platform/auth) credentials do not match the existing connection, causing the connection to enter the [failed state](/docs/connect/states).
 
 Examples of this error include:
 
@@ -217,13 +217,13 @@ Examples of this error include:
 
 This error occurs when an API key is used over a non-TLS (unencrypted) connection, which is not permitted due to security risks. API keys are long-lived credentials, making them more vulnerable if exposed. Unlike short-lived tokens, API keys remain valid indefinitely, meaning a compromised key presents a significant security risk.
 
-Non-TLS transports can be inspected by network devices routing traffic between the client and Ably. Ably does not allow API key authentication over non-TLS connections. However, Ably supports [basic authentication](/docs/auth/basic) over TLS and [token authentication](/docs/auth/token) over non-TLS connections.
+Non-TLS transports can be inspected by network devices routing traffic between the client and Ably. Ably does not allow API key authentication over non-TLS connections. However, Ably supports [basic authentication](/docs/platform/auth/basic) over TLS and [token authentication](/docs/platform/auth/token) over non-TLS connections.
 
-Resolution: Select the appropriate [authentication mechanism](/docs/auth#selecting-auth) for your use case.
+Resolution: Select the appropriate [authentication mechanism](/docs/platform/auth#selecting-auth) for your use case.
 
 ## 40104: Timestamp not current <a id="40104"/>
 
-This error occurs when a signed token request sent to Ably is too old. Ably enforces timestamp validation to ensure [`TokenRequest`](/docs/auth/token#token-request) remain valid for a limited time, reducing the risk of interception and misuse.
+This error occurs when a signed token request sent to Ably is too old. Ably enforces timestamp validation to ensure [`TokenRequest`](/docs/platform/auth/token#token-request) remain valid for a limited time, reducing the risk of interception and misuse.
 
 Resolutions: The following steps can help resolve this issue:
 * Ensure that the authentication servers clock is accurate when generating signed token requests.
@@ -238,7 +238,7 @@ This error occurs when a signed [token request](/docs/api/realtime-sdk/types#tok
 Examples of this error include:
 * A client sends a signed token request to Ably but does not receive the response due to network issues. If the client automatically retries the HTTP request in a fallback data center, Ably detects the duplicate nonce and rejects it.
 * An authentication server caches and reuses signed token requests instead of generating a unique one for each request.
-* A misconfigured [`authCallback`](/docs/auth/token#auth-callback) function reuses the same token request on every invocation instead of generating a fresh one.
+* A misconfigured [`authCallback`](/docs/platform/auth/token#auth-callback) function reuses the same token request on every invocation instead of generating a fresh one.
 * The `tokenRequest` is not renewed. A new token request should be requested from your server at this point:
 
 <Code>
@@ -262,9 +262,9 @@ Resolution: The following steps can help resolve this issue:
 
 ## 40106: Unable to obtain credentials from given parameters <a id="40106"/>
 
-This error occurs when invalid [authentication](/docs/auth) options (key or token) are provided to the Ably SDK, preventing successful authentication.
+This error occurs when invalid [authentication](/docs/platform/auth) options (key or token) are provided to the Ably SDK, preventing successful authentication.
 
-An example of this error is when no [API key](/docs/auth#api-keys) or [token](/docs/auth/token) is supplied, or when an authentication request is made using a token to request another token, instead of an API key.
+An example of this error is when no [API key](/docs/platform/auth#api-keys) or [token](/docs/platform/auth/token) is supplied, or when an authentication request is made using a token to request another token, instead of an API key.
 
 ## 40111: Connection limits exceeded <a id="40111"/>
 
@@ -296,7 +296,7 @@ This error occurs when the application has reached the maximum number of [API ke
 
 ## 40131: Key revoked <a id="40131"/>
 
-This error occurs when the [Ably API key](/docs/auth#api-keys) used to initialize the SDK is no longer valid because it has been [revoked](/docs/auth/revocation) by an admin of the application.
+This error occurs when the [Ably API key](/docs/platform/auth#api-keys) used to initialize the SDK is no longer valid because it has been [revoked](/docs/platform/auth/revocation) by an admin of the application.
 
 Resolution: The following steps can help resolve this issue:
 * If you are an admin, go to the [API keys tab](/docs/platform/account/app/api) in the Ably dashboard to check for valid keys. Use an existing valid key or create a new one with the necessary permissions.
@@ -304,7 +304,7 @@ Resolution: The following steps can help resolve this issue:
 
 ## 40133: Wrong key; cannot revoke tokens with a different key than the one that issued them <a id="40133"/>
 
-This error occurs when the [Ably API key](/docs/auth#api-keys) used to authorize a token [revocation](/docs/auth/revocation) request does not match the key that originally issued the token.
+This error occurs when the [Ably API key](/docs/platform/auth#api-keys) used to authorize a token [revocation](/docs/platform/auth/revocation) request does not match the key that originally issued the token.
 
 Resolution: The following steps can help resolve this issue:
 * Ensure that the public API key ID used in the request matches the key that originally issued the token.
@@ -312,56 +312,56 @@ Resolution: The following steps can help resolve this issue:
 
 ## 40141: Token revoked <a id="40141"/>
 
-This error occurs when attempting to authenticate with a [token](/docs/auth/token) that has been [revoked](/docs/auth/revocation) and is no longer valid.
+This error occurs when attempting to authenticate with a [token](/docs/platform/auth/token) that has been [revoked](/docs/platform/auth/revocation) and is no longer valid.
 
-Resolution: Ensure that you are using a valid, [non-revoked](/docs/auth/revocation). token for authentication. If needed, generate a new token and use it for authorization.
+Resolution: Ensure that you are using a valid, [non-revoked](/docs/platform/auth/revocation). token for authentication. If needed, generate a new token and use it for authorization.
 
 ## 40142: Token expired <a id="40142"/>
 
-This error occurs when the authentication [token](/docs/auth/token#refresh) has expired and is no longer valid for use.
+This error occurs when the authentication [token](/docs/platform/auth/token#refresh) has expired and is no longer valid for use.
 
 An example of this error is when a client attempts to authenticate with a token that has exceeded its time-to-live (TTL).
 
 Resolution: The following steps can help resolve this issue:
-* Use [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback) in your client configuration to enable automatic token renewal.
+* Use [`authUrl`](/docs/platform/auth/token#auth-url) or [`authCallback`](/docs/platform/auth/token#auth-callback) in your client configuration to enable automatic token renewal.
 * If `authUrl` or `authCallback` is correctly configured, the client SDK will automatically renew the token when needed, so you may see this error temporarily before renewal occurs.
 
 ## 40143: Token unrecognized <a id="40143"/>
 
-This error occurs when the provided token is not recognized as a valid Ably [token](/docs/auth/token), Ably [JWT](/docs/auth/token#jwt), or a JWT containing a valid Ably token.
+This error occurs when the provided token is not recognized as a valid Ably [token](/docs/platform/auth/token), Ably [JWT](/docs/platform/auth/token#jwt), or a JWT containing a valid Ably token.
 
 An example of this error is when a JWT is incorrectly formatted or when an Ably token does not follow the expected structure, for example: `<appId>.<randomBytes>`. Any token that does not adhere to the correct format will not be recognized.
 
-Resolution: Validate the token format before using it for authentication. If creating a [JWT](/docs/auth/token#jwt), use a standard JWT library to ensure correct generation. If using an Ably token, verify that it matches the expected format as returned from the [`requestToken`](/docs/api/token-request-spec#examples) endpoint.
+Resolution: Validate the token format before using it for authentication. If creating a [JWT](/docs/platform/auth/token#jwt), use a standard JWT library to ensure correct generation. If using an Ably token, verify that it matches the expected format as returned from the [`requestToken`](/docs/api/token-request-spec#examples) endpoint.
 
 ## 40144: Unexpected error decoding JWT; decode exception <a id="40144"/>
 
-This error occurs when the [JWT](/docs/auth/token#jwt). provided for authentication cannot be validated by Ably due to incorrect formatting, missing claims, or unsupported configurations.
+This error occurs when the [JWT](/docs/platform/auth/token#jwt). provided for authentication cannot be validated by Ably due to incorrect formatting, missing claims, or unsupported configurations.
 
-This error occurs when the [JWT](/docs/auth/token#jwt) provided for authentication cannot be validated by Ably. The specific reason for the failure will be available in the reason property of a [`ConnectionStateChange`](/docs/api/realtime-sdk/types#connection-state-change) object or in an error response from a REST request.
+This error occurs when the [JWT](/docs/platform/auth/token#jwt) provided for authentication cannot be validated by Ably. The specific reason for the failure will be available in the reason property of a [`ConnectionStateChange`](/docs/api/realtime-sdk/types#connection-state-change) object or in an error response from a REST request.
 
 Examples of this error include:
 * Missing or invalid payload claims, such as iat (issued at) or exp (expiration).
 * Using a deprecated or unsupported signing algorithm.
 * Providing an empty string for `x-ably-capability`.
-* Using an empty string or non-string value for [`x-ably-revocation-key`](/docs/auth/revocation#revocation-key).
+* Using an empty string or non-string value for [`x-ably-revocation-key`](/docs/platform/auth/revocation#revocation-key).
 * Missing kid (Key ID) when using [JWT authentication with an API key](/docs/api/realtime-sdk/authentication#ably-jwt).
 
 ## 40160: Action not permitted <a id="40160"/>
 
 This error occurs when the client does not have permission to perform the requested action.
 
-An example of this error is when a token request includes an empty [capability object](/docs/auth/capabilities#capabilities-token), for example: `({})`, meaning the client has no assigned permissions, or when the requested [resource](/docs/auth/capabilities#wildcards) does not match the API key's allowed capabilities.
+An example of this error is when a token request includes an empty [capability object](/docs/platform/auth/capabilities#capabilities-token), for example: `({})`, meaning the client has no assigned permissions, or when the requested [resource](/docs/platform/auth/capabilities#wildcards) does not match the API key's allowed capabilities.
 
-Resolution: Ensure the [API key](/docs/auth#api-keys) supports the required [capabilities](/docs/auth/capabilities#capabilities-key) for the requested action.
+Resolution: Ensure the [API key](/docs/platform/auth#api-keys) supports the required [capabilities](/docs/platform/auth/capabilities#capabilities-key) for the requested action.
 
 ## 40161: Access denied to channel: namespace requires identified clients <a id="40161"/>
 
-This error occurs when a [non-identified client](/docs/auth/identified-clients) attempts to access a channel that requires an identified client. Each application's channel namespaces configuration can be found in its application settings. By default, the identified namespace requires a client to be identified.
+This error occurs when a [non-identified client](/docs/platform/auth/identified-clients) attempts to access a channel that requires an identified client. Each application's channel namespaces configuration can be found in its application settings. By default, the identified namespace requires a client to be identified.
 
 ## 40170: Error from client token callback <a id="40170"/>
 
-This error occurs when an authentication attempt using [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback) fails due to a timeout, network issue, invalid token format, or another authentication error condition.
+This error occurs when an authentication attempt using [`authUrl`](/docs/platform/auth/token#auth-url) or [`authCallback`](/docs/platform/auth/token#auth-callback) fails due to a timeout, network issue, invalid token format, or another authentication error condition.
 
 Examples of this error include when a `TokenRequest` callback times out after the default 10-second limit. Also, when he `authUrl` response is missing a Content-Type header has an unsupported Content-Type.
 
@@ -375,7 +375,7 @@ Resolution: The following steps can help resolve this issue:
 
 ## 40171: No means provided to renew auth token <a id="40171"/>
 
-This error occurs when no [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback) is provided in [`clientOptions`](/docs/getting-started/setup#options) when initializing the Ably REST or Realtime SDK.
+This error occurs when no [`authUrl`](/docs/platform/auth/token#auth-url) or [`authCallback`](/docs/platform/auth/token#auth-callback) is provided in [`clientOptions`](/docs/getting-started/setup#options) when initializing the Ably REST or Realtime SDK.
 
 Tokens have a set expiration time, and once expired, they are no longer valid for communication with Ably. If `authUrl` or `authCallback` is configured, the SDK will automatically request a new token before expiration, ensuring uninterrupted operation.
 
@@ -624,7 +624,7 @@ Resolution: If you are seeing resumes failing in ably-js, this was a known bug i
 
 ## 80019: Auth server rejecting request <a id="80019"/>
 
-This error occurs when the client library fails to obtain a token using the client-supplied [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback). It is raised when the request to the authentication server fails due to an error or exception in the callback.
+This error occurs when the client library fails to obtain a token using the client-supplied [`authUrl`](/docs/platform/auth/token#auth-url) or [`authCallback`](/docs/platform/auth/token#auth-callback). It is raised when the request to the authentication server fails due to an error or exception in the callback.
 
 ## 80020: Continuity loss due to maximum subscribe message rate exceeded <a id="80020"/>
 
@@ -686,7 +686,7 @@ This error occurs when the [maximum](/docs/platform/pricing/limits#channel) rate
 This error occurs when a client attempts to [enter](/docs/chat/rooms/presence#set) the [presence](/docs/presence-occupancy/presence) set of a channel without specifying a `clientId`.
 
 A client can be identified in several ways:
-* If using [token](/docs/auth/token) authentication, ensure the token is associated with a `clientId` by setting the `clientId` field in `tokenParams` when creating a token request or requesting a token.
+* If using [token](/docs/platform/auth/token) authentication, ensure the token is associated with a `clientId` by setting the `clientId` field in `tokenParams` when creating a token request or requesting a token.
 * If using basic authentication or token authentication with a wildcard `clientId`, set the `clientId` in the client options when initializing the Ably SDK.
 * Specify a `clientId` at the time of entering presence using [`enterClient()`](/docs/api/realtime-sdk/presence#enterclient).
 
diff --git a/src/pages/docs/platform/integrations/inbound/kafka-connector.mdx b/src/pages/docs/platform/integrations/inbound/kafka-connector.mdx
index e659321385..7c02890cfb 100644
--- a/src/pages/docs/platform/integrations/inbound/kafka-connector.mdx
+++ b/src/pages/docs/platform/integrations/inbound/kafka-connector.mdx
@@ -22,7 +22,7 @@ Install the Ably Kafka Connector from:
 * [GitHub](https://github.com/ably/kafka-connect-ably) to run within your own infrastructure.
 * [Confluent Hub](https://www.confluent.io/hub/ably/kafka-connect-ably) to run on the Confluent Platform.
 
-Once installed, configure it with your [Ably API key](/docs/auth#api-keys) to enable data from Kafka topics to be published into Ably channels.
+Once installed, configure it with your [Ably API key](/docs/platform/auth#api-keys) to enable data from Kafka topics to be published into Ably channels.
 
 ## Mapping <a id="mapping"/>
 
diff --git a/src/pages/docs/platform/integrations/inbound/webhooks.mdx b/src/pages/docs/platform/integrations/inbound/webhooks.mdx
index 2cd8085b50..55250ab825 100644
--- a/src/pages/docs/platform/integrations/inbound/webhooks.mdx
+++ b/src/pages/docs/platform/integrations/inbound/webhooks.mdx
@@ -57,6 +57,10 @@ A successful request returns a `201` status. Failures return with an [`ErrorInfo
 
 Incoming webhooks publish messages to an Ably channel. You can [subscribe](/docs/pub-sub#subscribe) to these messages using an Ably SDK:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```javascript
 const Ably = require("ably");
diff --git a/src/pages/docs/platform/integrations/skip-integrations.mdx b/src/pages/docs/platform/integrations/skip-integrations.mdx
index 8fe5f0bc44..96893e30cb 100644
--- a/src/pages/docs/platform/integrations/skip-integrations.mdx
+++ b/src/pages/docs/platform/integrations/skip-integrations.mdx
@@ -11,7 +11,7 @@ Privileged users can skip integrations on a per-message basis, providing greater
 A strong use case for skipping integrations is in chat applications. For example, a moderation service publishes a command telling clients to edit or delete a message. That command should not trigger further moderation events by itself.
 
 <Aside data-type='note'>
-Clients must have the [privileged-headers](/docs/auth/capabilities#capability-operations) capability enabled in their Ably [API key](/docs/auth) or [token](/docs/auth/token) to skip integrations.
+Clients must have the [privileged-headers](/docs/platform/auth/capabilities#capability-operations) capability enabled in their Ably [API key](/docs/platform/auth) or [token](/docs/platform/auth/token) to skip integrations.
 </Aside>
 
 ## Skip all integrations
@@ -20,6 +20,10 @@ To skip all integration rules for a specific message, set the `skipRule` field t
 
 The following example shows how to skip all integration rules when publishing a message to a channel:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```javascript
 const rest = new Ably.Rest('{{API_KEY}}');
diff --git a/src/pages/docs/platform/integrations/streaming/index.mdx b/src/pages/docs/platform/integrations/streaming/index.mdx
index 1c59b6ae4e..fb2ff1ce81 100644
--- a/src/pages/docs/platform/integrations/streaming/index.mdx
+++ b/src/pages/docs/platform/integrations/streaming/index.mdx
@@ -145,6 +145,10 @@ Non-enveloped messages use a more straightforward format, delivering events dire
 
 For example, if you publish a JSON message to the channel `my_channel` using the following cURL request:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```shell
 curl -X POST https://main.realtime.ably.net/channels/my_channel/messages \
diff --git a/src/pages/docs/platform/integrations/webhooks/index.mdx b/src/pages/docs/platform/integrations/webhooks/index.mdx
index 484ebdbaa7..f800e7671b 100644
--- a/src/pages/docs/platform/integrations/webhooks/index.mdx
+++ b/src/pages/docs/platform/integrations/webhooks/index.mdx
@@ -467,6 +467,10 @@ The payload will contain the data of the message.
 
 For example, if you publish a message to the channel `my_channel` using the following cURL request:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```shell
 curl -X POST https://main.realtime.ably.net/channels/my_channel/messages \
diff --git a/src/pages/docs/platform/pricing/limits.mdx b/src/pages/docs/platform/pricing/limits.mdx
index 8f4e30662e..431305e66b 100644
--- a/src/pages/docs/platform/pricing/limits.mdx
+++ b/src/pages/docs/platform/pricing/limits.mdx
@@ -136,7 +136,7 @@ Integration limits relate to the rate and concurrency of [webhooks](/docs/platfo
 
 ## API limits <a id="api"/>
 
-API request limits are the maximum number of [REST API](/docs/api/rest-api) requests, [Control API](/docs/platform/account/control-api) requests and [token requests](/docs/auth/token) that can be made to Ably.
+API request limits are the maximum number of [REST API](/docs/api/rest-api) requests, [Control API](/docs/platform/account/control-api) requests and [token requests](/docs/platform/auth/token) that can be made to Ably.
 
 | API request limit | Free | Standard | Pro | Enterprise |
 | ----------------- | ---- | -------- | --- | ---------- |
diff --git a/src/pages/docs/presence-occupancy/presence.mdx b/src/pages/docs/presence-occupancy/presence.mdx
index 0821f8d34c..e3a19b6aa7 100644
--- a/src/pages/docs/presence-occupancy/presence.mdx
+++ b/src/pages/docs/presence-occupancy/presence.mdx
@@ -19,7 +19,7 @@ Presence enables clients to be aware of other clients that are currently "presen
 Other devices and services can subscribe to presence events in real time using the realtime interface or with [integrations](/docs/platform/integrations). You can also request a list of clients or devices on a channel at a particular point in time with the REST interface.
 
 <Aside data-type="important">
-Clients must be [identified](/docs/auth/identified-clients) by having a `ClientId` in order to be present on a channel. They also require the `presence` [capability](/docs/auth/capabilities) to enter the presence set, and the `subscribe` capability to subscribe to presence events.
+Clients must be [identified](/docs/platform/auth/identified-clients) by having a `ClientId` in order to be present on a channel. They also require the `presence` [capability](/docs/platform/auth/capabilities) to enter the presence set, and the `subscribe` capability to subscribe to presence events.
 </Aside>
 
 ## Trigger presence events <a id="trigger-events"/>
@@ -247,6 +247,10 @@ A single [`clientId`](/docs/api/realtime-sdk#client-id) may be present multiple
 
 In order to be able to publish presence changes for arbitrary client IDs, the SDK must have been instantiated either with an [API key](https://faqs.ably.com/what-is-an-app-api-key), or with a [token bound to a wildcard client ID](https://faqs.ably.com/can-a-client-emulate-any-client-id-i.e.-authenticate-using-a-wildcard-client-id).
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```rest_javascript
 const rest = new Ably.Rest({ key: '{{API_KEY}}' });
@@ -623,7 +627,7 @@ Using server-side batching for presence events can reduce message costs when the
 
 ### Be present without subscribing to presence events <a id="present-no-subscribe"/>
 
-Messages are streamed to clients as soon as they [attach](/docs/channels/states#attach) to a channel, as long as they have the [subscribe capability](/docs/auth/capabilities).
+Messages are streamed to clients as soon as they [attach](/docs/channels/states#attach) to a channel, as long as they have the [subscribe capability](/docs/platform/auth/capabilities).
 
 Efficient use of capabilities can prevent clients from receiving presence events while still allowing them to enter the presence set. This is a common scenario when you want lots of people to be present without necessarily listening for presence change events, such as when you just want to know how many people are present on a channel at any point in time.
 
diff --git a/src/pages/docs/protocols/index.mdx b/src/pages/docs/protocols/index.mdx
index 8f4c6a4a2a..00fe40d499 100644
--- a/src/pages/docs/protocols/index.mdx
+++ b/src/pages/docs/protocols/index.mdx
@@ -5,7 +5,7 @@ redirect_from:
   - /docs/protocol-adapters
 ---
 
-Ably SDKs are the recommended method for connecting to Ably because they offer support for a comprehensive set of Ably features, such as automatic [connection management](/docs/connect), [authentication token renewal](/docs/auth/token) and [presence](/docs/presence-occupancy).
+Ably SDKs are the recommended method for connecting to Ably because they offer support for a comprehensive set of Ably features, such as automatic [connection management](/docs/connect), [authentication token renewal](/docs/platform/auth/token) and [presence](/docs/presence-occupancy).
 
 Protocol adapters offer an alternative method for connecting to Ably. The advantage to protocol adapters is that they require fewer resources in terms of memory and network overhead such as in smaller footprint devices, or on a platform where an Ably SDK isn't available such as an Arduino-based IoT wearable. The potential drawback to consider when evaluating protocol adapters is that they do not support the full set of Ably features, for example the MQTT protocol adapter does not support presence, and the SSE protocol adapter does not support automatic token renewal.
 
diff --git a/src/pages/docs/protocols/mqtt.mdx b/src/pages/docs/protocols/mqtt.mdx
index 62779c03e9..ddb7e10ced 100644
--- a/src/pages/docs/protocols/mqtt.mdx
+++ b/src/pages/docs/protocols/mqtt.mdx
@@ -62,9 +62,9 @@ var client = mqtt.connect('mqtts:main.mqtt.ably.net', options);
 
 ### Token Authentication <a id="token-auth"/>
 
-Ably recommends that you always make use of [token Authentication over basic Authentication](/docs/auth) when trying to connect from devices you may not trust. In addition, if you're using Basic Authentication you'll be required to use SSL to connect to our adapter to ensure the API key cannot be accessed by someone listening in.
+Ably recommends that you always make use of [token Authentication over basic Authentication](/docs/platform/auth) when trying to connect from devices you may not trust. In addition, if you're using Basic Authentication you'll be required to use SSL to connect to our adapter to ensure the API key cannot be accessed by someone listening in.
 
-For Token Authentication you'll be required to [create a token from your own servers](/docs/auth/token). Once you have the token, you can simply pass it through when trying to connect to Ably as the connection's `username`, leaving the `password` empty.
+For Token Authentication you'll be required to [create a token from your own servers](/docs/platform/auth/token). Once you have the token, you can simply pass it through when trying to connect to Ably as the connection's `username`, leaving the `password` empty.
 
 If using Token Authentication, you can subscribe to a special topic, `[mqtt]tokenevents`, to get a warning when the current connection's token is about to expire. This will be a single message, sent 30 seconds before the token expires, with the 13 byte payload `expirywarning`.
 
@@ -96,10 +96,120 @@ client.on('message', function(topic, message) {
 ```
 </Code>
 
+### JWT Authentication <a id="jwt-auth"/>
+
+<Aside data-type='note'>
+For most MQTT use cases, especially IoT and embedded devices, JWT authentication is the recommended approach over TokenRequest. JWTs can be created with any JWT library (no Ably SDK required), work well with device provisioning workflows, and support advanced features like channel-scoped claims and per-connection rate limits.
+</Aside>
+
+For IoT devices and embedded systems, [Ably JWT](/docs/platform/auth/token#choosing-jwt) is often the best authentication choice because:
+
+- No Ably SDK required on the device
+- Any JWT library (or manual JWT creation) works
+- JWTs can be provisioned during device setup and renewed as needed
+
+Your provisioning server creates JWTs for devices:
+
+**Provisioning server:**
+
+<Code>
+```javascript
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+function createDeviceJwt(deviceId) {
+  return jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({
+        [`devices:${deviceId}:telemetry`]: ['publish'],
+        [`devices:${deviceId}:commands`]: ['subscribe'],
+      }),
+      'x-ably-clientId': deviceId,
+    },
+    keySecret,
+    {
+      algorithm: 'HS256',
+      keyid: keyName,
+      expiresIn: '24h',
+    }
+  );
+}
+```
+
+```python
+import jwt
+import os
+import json
+import time
+
+def create_device_jwt(device_id: str) -> str:
+    api_key = os.environ['ABLY_API_KEY']
+    key_name, key_secret = api_key.split(':')
+
+    now = int(time.time())
+
+    return jwt.encode(
+        {
+            'iat': now,
+            'exp': now + 86400,  # 24 hours
+            'x-ably-capability': json.dumps({
+                f'devices:{device_id}:telemetry': ['publish'],
+                f'devices:{device_id}:commands': ['subscribe'],
+            }),
+            'x-ably-clientId': device_id,
+        },
+        key_secret,
+        algorithm='HS256',
+        headers={'kid': key_name}
+    )
+```
+</Code>
+
+The device uses the JWT as the MQTT username, with an empty password:
+
+**Device client:**
+
+<Code>
+```javascript
+const mqtt = require('mqtt');
+
+const jwtToken = getJwtFromProvisioning(); // Get JWT from your provisioning server
+
+const client = mqtt.connect('mqtts://main.mqtt.ably.net:8883', {
+  username: jwtToken,  // The Ably JWT
+  password: '',        // Empty password
+  keepalive: 30,
+});
+
+client.on('connect', () => {
+  console.log('Connected with JWT');
+  client.subscribe('[mqtt]tokenevents'); // Subscribe for token expiry warnings
+  client.subscribe('devices/my-device/commands');
+});
+
+client.on('message', (topic, message) => {
+  if (topic === '[mqtt]tokenevents' && message.toString() === 'expirywarning') {
+    // Get new JWT and reconnect
+    const newJwt = getNewJwtFromServer();
+    client.end();
+    client.options.username = newJwt;
+    client.reconnect();
+  }
+});
+```
+</Code>
+
+See [Choosing a token mechanism](/docs/platform/auth/token#choosing) for when to use JWT vs TokenRequest authentication.
+
 ## Pub/Sub with MQTT <a id="pub-sub"/>
 
 [Ably's channels](/docs/channels) correlate to topics in MQTT. An example of how to publish and subscribe with the NodeJS [MQTT package](https://www.npmjs.com/package/mqtt) would be as follows:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#jwt-auth).
+</Aside>
+
 <Code>
 ```javascript
 const mqtt = require('mqtt');
@@ -118,9 +228,9 @@ client.on('message', function(topic, message) {
   console.log(decoder.decode(message));
 });
 
-client.subscribe('my_channel', function (err) {
+client.subscribe('your-channel', function (err) {
   if (!err) {
-    client.publish('my_channel', 'my_message', { qos: 0 });
+    client.publish('your-channel', 'your_message', { qos: 0 });
   }
 });
 ```
@@ -130,11 +240,15 @@ client.subscribe('my_channel', function (err) {
 
 Any data published through or received by the MQTT adapter will be binary encoded, due to MQTT being a binary protocol. This means that you'll need to interpret the message to get the original contents out. For example, to interpret a message using Ably Realtime with JavaScript you'd need to do the following, using the [text-encoding NPM module's TextDecoder](https://www.npmjs.com/package/text-encoding) to decode from binary to text:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#jwt-auth).
+</Aside>
+
 <Code>
 ```javascript
 var ably = new Ably.Realtime('{{API_KEY}}');
 var decoder = new TextDecoder();
-var channel = ably.channels.get('my_channel');
+var channel = ably.channels.get('your-channel');
 
 channel.subscribe(function(message) {
   var command = decoder.decode(message.data);
@@ -147,7 +261,7 @@ var decoder = new encoding.TextDecoder();
 var client = mqtt.connect('mqtts:main.mqtt.ably.net', options);
 
 client.on('connect', function () {
-  client.subscribe('my_channel');
+  client.subscribe('your-channel');
 });
 
 client.on('message', function (topic, message) {
@@ -160,7 +274,7 @@ In the above example, `command` will now contain the message in its original str
 
 ## SSL/TLS <a id="ssl-tls"/>
 
-Ably supports both SSL and non-SSL connections (the latter uses a different port, see above), but strongly recommends using SSL wherever possible. If you are not using SSL, note that the same restrictions apply as if you were using an Ably client without SSL. That is, [connection attempts using Basic Authentication (i.e. an API key) are disallowed](/docs/auth/basic), and any [namespaces which you've enabled 'require TLS' on](/docs/channels) will be inaccessible. [Contact us](https://ably.com/support) if this is a problem for you.
+Ably supports both SSL and non-SSL connections (the latter uses a different port, see above), but strongly recommends using SSL wherever possible. If you are not using SSL, note that the same restrictions apply as if you were using an Ably client without SSL. That is, [connection attempts using Basic Authentication (i.e. an API key) are disallowed](/docs/platform/auth/basic), and any [namespaces which you've enabled 'require TLS' on](/docs/channels) will be inaccessible. [Contact us](https://ably.com/support) if this is a problem for you.
 
 ## Channel options <a id="channel-options"/>
 
@@ -182,6 +296,10 @@ Read more in the [delta section](/docs/channels/options/deltas).
 
 #### Delta example <a id="delta-example"/>
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#jwt-auth).
+</Aside>
+
 <Code>
 ```javascript
   var mqtt = require('mqtt');
@@ -194,7 +312,7 @@ Read more in the [delta section](/docs/channels/options/deltas).
     port: 8883
   };
   var client = mqtt.connect('mqtts:main.mqtt.ably.net', options);
-  var channelName = 'sample-app-mqtt';
+  var channelName = 'your-channel';
   var channelDecoder = new VcdiffDecoder();
 
   client.on('message', (_, payload) => {
@@ -227,6 +345,10 @@ Read more in the [Rewind section.](/docs/channels/options/rewind).
 
 #### Rewind example <a id="rewind-example"/>
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#jwt-auth).
+</Aside>
+
 <Code>
 ```javascript
 var mqtt = require('mqtt');
@@ -238,7 +360,7 @@ var options = {
 };
 var client = mqtt.connect('mqtts:main.mqtt.ably.net', options);
 client.on('connect', () => {
-  client.subscribe('[?rewind=1]{{RANDOM_CHANNEL_NAME}}');
+  client.subscribe('[?rewind=1]your-channel');
 });
 client.on('message', (topic, message) => {
   ...
diff --git a/src/pages/docs/protocols/pubnub.mdx b/src/pages/docs/protocols/pubnub.mdx
index 96e0ccc928..d91223eba6 100644
--- a/src/pages/docs/protocols/pubnub.mdx
+++ b/src/pages/docs/protocols/pubnub.mdx
@@ -52,6 +52,10 @@ The following PubNub features are not supported using the adapter:
 
 Initialize your PubNub SDK to connect to Ably. All of PubNub's SDKs are supported.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 The following is an example of initializing the PubNub SDK:
 
 <Code>
@@ -78,7 +82,7 @@ pubnub = Pubnub.new(
 </Code>
 
 <Aside data-type='note'>
-PubNub uses different API keys for publishing and subscribing. Ably does not use different keys and instead manages access through API key and token [capabilities](/docs/auth/capabilities). The adapter will use the value passed to `subscribe_key` to create a connection to Ably. If that API key doesn't have publish capabilities, the client won't be able to publish.
+PubNub uses different API keys for publishing and subscribing. Ably does not use different keys and instead manages access through API key and token [capabilities](/docs/platform/auth/capabilities). The adapter will use the value passed to `subscribe_key` to create a connection to Ably. If that API key doesn't have publish capabilities, the client won't be able to publish.
 </Aside>
 
 | Option | Description |
diff --git a/src/pages/docs/protocols/pusher.mdx b/src/pages/docs/protocols/pusher.mdx
index f4661c728f..7f78c1e869 100644
--- a/src/pages/docs/protocols/pusher.mdx
+++ b/src/pages/docs/protocols/pusher.mdx
@@ -28,7 +28,7 @@ The following Pusher features are supported using the adapter:
 The Pusher protocol is not supported by default in Ably apps. This is due to security reasons associated with the use of public channels.
 
 <Aside data-type='important'>
-Normally, it is not possible to connect to Ably without a complete API key, or a [token](/docs/auth/token) derived from one. When the Pusher Adapter is enabled, you can connect to Pusher public channels with only the Ably API [key name](/docs/auth#format). The key name is a combination of the app ID and the key ID.
+Normally, it is not possible to connect to Ably without a complete API key, or a [token](/docs/platform/auth/token) derived from one. When the Pusher Adapter is enabled, you can connect to Pusher public channels with only the Ably API [key name](/docs/platform/auth#format). The key name is a combination of the app ID and the key ID.
 </Aside>
 
 To enable the Pusher Adapter in an app:
@@ -63,7 +63,7 @@ const pusher = new Pusher('appId.keyId', {
 </Code>
 
 <Aside data-type='note'>
-You should only use your [Ably API key name](/docs/auth#format), not the full API key. This includes everything before the colon `:` in your API key.
+You should only use your [Ably API key name](/docs/platform/auth#format), not the full API key. This includes everything before the colon `:` in your API key.
 </Aside>
 
 | Option | Description |
diff --git a/src/pages/docs/protocols/sse.mdx b/src/pages/docs/protocols/sse.mdx
index 173bda2338..ce8688b0b6 100644
--- a/src/pages/docs/protocols/sse.mdx
+++ b/src/pages/docs/protocols/sse.mdx
@@ -42,10 +42,14 @@ SSE is an excellent alternative to Ably SDK in memory-limited environments.
 
 The following code sample provides an example of how to use SSE with Ably:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#auth).
+</Aside>
+
 <Code>
 ```javascript
 var apiKey ='{{API_KEY}}';
-var url ='https://main.realtime.ably.net/event-stream?channels=myChannel&v=1.2&key=' + apiKey;
+var url ='https://main.realtime.ably.net/event-stream?channels=your-channel&v=1.2&key=' + apiKey;
 var eventSource = new EventSource(url);
 
 eventSource.onmessage = function(event) {
@@ -57,64 +61,136 @@ eventSource.onmessage = function(event) {
 
 ## Authentication <a id="auth"/>
 
-Authentication with SSE allows for two methods: [basic auth](/docs/auth/basic) using an [API key](/docs/getting-started/setup) or [token auth](/docs/auth/token), using a token from your server. For enhanced security and control over connections, token auth is recommended for client-side use. Basic auth is simpler as it omits the need for an auth server and the potential need for clients to refresh expired tokens.
-
-It is possible to use either [basic auth](/docs/auth/basic), with an [API key](/docs/getting-started/setup), or [token auth](/docs/auth/token), with a [token issued from your server](/docs/auth/token), with SSE. It's recommended to use token auth on the client side for [security reasons](/docs/auth), so you have control over who can connect. Basic auth, while lacking this control, is simpler (it doesn't require you to run an auth server), and you don't have to worry about the client obtaining a new token when the old one expires.
+SSE supports [basic authentication](/docs/platform/auth/basic) with an API key, or [token authentication](/docs/platform/auth/token) with tokens from your server. **For client-side applications, [JWT token authentication](/docs/platform/auth/token#choosing-jwt) is recommended.**
 
-If using basic auth, you can use a querystring parameter of `key` or an `Authorization: Basic <base64-encoded key>` header. If using token auth, you can use an `accessToken` querystring parameter or an `Authorization: Bearer <base64-encoded token>` header. See [REST API authentication](/docs/auth) for more information.
+- **Basic auth**: Use the `key` querystring parameter or `Authorization: Basic <base64-encoded key>` header
+- **Token auth**: Use the `accessToken` querystring parameter or `Authorization: Bearer <token>` header
 
 Note that [connection state](/docs/connect) is only retained for two minutes.
 
-The SSE protocol and EventSource API seamlessly resume dropped connections. The client reconnects, supplying a `lastEventId` parameter, ensuring no event is missed from the previous connection's endpoint. Ably uses this feature to resume channels from where they left off.
+### JWT Authentication (recommended) <a id="jwt-auth"/>
 
-At the point of token expiration, the connection terminates. The default EventSource reconnection won't function due to the expired credentials embedded in the connection URL. The solution is initiating a new connection with an updated `accessToken`, ensuring continuity by providing the right `lastEventId` for a seamless transition from the previous connection's endpoint.
+<Aside data-type='note'>
+For SSE clients, JWT authentication is recommended because JWTs can be created with any JWT library (no Ably SDK required on your server) and provide features like channel-scoped claims.
+</Aside>
 
-### Implementing message continuity with token auth <a id="message-continuity-token-auth"/>
+Your server creates JWTs for clients to use with the `accessToken` parameter:
 
-To enable transparent connection resumption when tokens must be renewed:
+**Server-side JWT creation:**
 
-1. Detect token expiration.
-2. Resume the connection precisely from the last delivered message using the `lastEventId` attribute.
+<Code>
+```javascript
+import jwt from 'jsonwebtoken';
 
-#### Detecting token expiry <a id="detecting-token-expiry"/>
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
 
-If there is an error that causes a connection to be interrupted, the `error` event will be activated on the `EventSource` instance. This applies to all types of connection disruptions. The data attribute of the event provides an Ably error body that describes the cause of the error. If the issue is related to the authorization token, the error code will indicate this. Token-related errors are identified by codes in the range of `40140 <= code < 40150`. In these situations, a new `accessToken` can be obtained and authentication can be attempted again.
+function createAblyJwt(clientId) {
+  return jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({ '*': ['subscribe'] }),
+      'x-ably-clientId': clientId,
+    },
+    keySecret,
+    {
+      algorithm: 'HS256',
+      keyid: keyName,
+      expiresIn: '1h',
+    }
+  );
+}
+```
 
-#### Specifying the lastEventId <a id="specifying-lasteventid"/>
+```python
+import jwt
+import os
+import json
+import time
+
+def create_ably_jwt(client_id: str) -> str:
+    api_key = os.environ['ABLY_API_KEY']
+    key_name, key_secret = api_key.split(':')
+
+    now = int(time.time())
+
+    return jwt.encode(
+        {
+            'iat': now,
+            'exp': now + 3600,
+            'x-ably-capability': json.dumps({'*': ['subscribe']}),
+            'x-ably-clientId': client_id,
+        },
+        key_secret,
+        algorithm='HS256',
+        headers={'kid': key_name}
+    )
+```
+</Code>
 
-When you receive a message on a connection, it will include a `lastEventId` attribute with the last `ID`. To set this value for a new connection, specify it as a `lastEvent` parameter in the URL.
+**Client-side SSE connection with JWT:**
+
+<Code>
+```javascript
+// Fetch JWT from your auth server
+const response = await fetch('/api/ably-token');
+const jwt = await response.text();
 
-The following is an example of implementing message continuity with token auth:
+// Connect to SSE with the JWT
+const url = `https://main.realtime.ably.net/event-stream?channels=your-channel&v=1.2&accessToken=${jwt}`;
+const eventSource = new EventSource(url);
+
+eventSource.onmessage = function(event) {
+  const message = JSON.parse(event.data);
+  console.log('Message:', message.name, '-', message.data);
+};
+```
+</Code>
+
+### Token expiration and message continuity <a id="token-continuity"/>
+
+The SSE protocol and EventSource API seamlessly resume dropped connections. The client reconnects, supplying a `lastEventId` parameter, ensuring no event is missed from the previous connection's endpoint.
+
+At the point of token expiration, the connection terminates. The default EventSource reconnection won't function due to the expired credentials embedded in the connection URL. The solution is initiating a new connection with an updated token, ensuring continuity by providing the right `lastEventId`.
+
+To enable transparent connection resumption when tokens must be renewed:
+
+1. Detect token expiration (error codes `40140` to `40149`)
+2. Fetch a new JWT from your auth server
+3. Resume the connection with the `lastEventId` from the previous connection
+
+The following example shows message continuity with JWT authentication:
 
 <Code>
 ```javascript
 let lastEvent;
+let eventSource;
+const channel = 'your-channel';
 
-const connectToAbly = () => {
-  // obtain a token
-  const token = <GET-NEW-ABLY-AUTH-TOKEN>
+async function connectToAbly() {
+  // Fetch JWT from your auth server
+  const response = await fetch('/api/ably-token');
+  const jwt = await response.text();
 
-  // establish a connection with that token
+  // Establish connection with JWT, resuming from lastEvent if available
   const lastEventParam = lastEvent ? ('&lastEvent=' + lastEvent) : '';
-  eventSource = new EventSource(`https://main.realtime.ably.net/sse?v=1.1&accessToken=${token}&channels=${channel}${lastEventParam}`);
+  eventSource = new EventSource(
+    `https://main.realtime.ably.net/sse?v=1.2&accessToken=${jwt}&channels=${channel}${lastEventParam}`
+  );
 
-  // handle incoming messages
+  // Track lastEventId for message continuity
   eventSource.onmessage = msg => {
     lastEvent = msg.lastEventId;
-    // ... normal message processing
-  }
+    // ... process message
+  };
 
-  // handle connection errors
+  // Handle token expiry
   eventSource.onerror = msg => {
     const err = JSON.parse(msg.data);
     const isTokenErr = err.code >= 40140 && err.code < 40150;
-    if(isTokenErr) {
+    if (isTokenErr) {
       eventSource.close();
-      connectToAbly();
-    } else {
-      // ... handle other types of error -- for example, retry on 5xxxx, close on 4xxxx
+      connectToAbly(); // Reconnect with fresh JWT
     }
-  }
+  };
 }
 
 connectToAbly();
@@ -156,11 +232,15 @@ For more information, see [Deltas](/docs/channels/options/deltas).
 
 You can subscribe to messages in delta mode, using the SSE transport, as follows.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#auth).
+</Aside>
+
 <Code>
 ```javascript
   /* Make sure to include <script src="https://cdn.ably.com/lib/delta-codec.min-1.js"></script> in your head */
   var key = '{{API_KEY}}';
-  var channel = '{{RANDOM_CHANNEL_NAME}}';
+  var channel = 'your-channel';
   var baseUrl = 'https://main.realtime.ably.net/event-stream';
   var urlParams = `?channels=${channel}&v=1.1&key=${key}&delta=vcdiff`;
   var url = baseUrl + urlParams;
@@ -195,13 +275,17 @@ You can subscribe to messages in delta mode, using the SSE transport, as follows
 
 For more information on enveloped and unenveloped SSE, please see the [SSE API](/docs/api/sse#sse)
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#auth).
+</Aside>
+
 <Code>
 ```javascript
   /* Make sure to include <script src="https://cdn.ably.com/lib/delta-codec.min-1.js"></script> in your head */
   var DeltaCodec = require('@ably/delta-codec');
 
   var key = '{{API_KEY}}';
-  var channel = 'sample-app-sse';
+  var channel = 'your-channel';
   var baseUrl = 'https://main.realtime.ably.net/event-stream';
   var urlParams = `?channels=${channel}&v=1.1&key=${key}&delta=vcdiff&enveloped=false`;
   var url = baseUrl + urlParams;
@@ -232,9 +316,13 @@ For more information on enveloped and unenveloped SSE, please see the [SSE API](
 
 You can use the [`rewind`](/docs/channels/options/rewind) channel option to choose the starting point of an attachment, either by specifying a specific moment in the past or a certain number of messages. For example, apply the `rewind` channel option with a value of `1` to all channels using a querystring parameter.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](#auth).
+</Aside>
+
 <Code>
 ```javascript
-  var querystring = 'v=1.2&channels={{RANDOM_CHANNEL_NAME}}&rewind=1&key={{API_KEY}}';
+  var querystring = 'v=1.2&channels=your-channel&rewind=1&key={{API_KEY}}';
   var eventSource = new EventSource('https://main.realtime.ably.net/event-stream?' + querystring);
 ```
 </Code>
@@ -243,8 +331,8 @@ Or to specify the same parameter but only applying to one channel of two, using
 
 <Code>
 ```javascript
-  var channelOne = encodeURIComponent('[?rewind=1]channel1');
-  var channelTwo = 'channel2';
+  var channelOne = encodeURIComponent('[?rewind=1]channel-one');
+  var channelTwo = 'channel-two';
   var channels = channelOne + ',' + channelTwo;
   var querystring = 'v=1.2&key={{API_KEY}}&channels=' + channels';
   var eventSource = new EventSource('https://main.realtime.ably.net/event-stream?' + querystring);
diff --git a/src/pages/docs/pub-sub/advanced.mdx b/src/pages/docs/pub-sub/advanced.mdx
index c5292d7f4b..467384ff7c 100644
--- a/src/pages/docs/pub-sub/advanced.mdx
+++ b/src/pages/docs/pub-sub/advanced.mdx
@@ -11,6 +11,10 @@ Explore additional concepts and features after understanding the [basics of subs
 
 As a reminder, you can subscribe to all messages on a channel:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
 const realtime = new Ably.Realtime('{{API_KEY}}');
@@ -274,7 +278,7 @@ unsubscribe()
 
 ### Attaching versus subscribing <a id="attach-subscribe"/>
 
-Messages are streamed to clients as soon as they attach to a channel, as long as they have the `subscribe` [capability](/docs/auth/capabilities) for it. This is independent of whether or not they have subscribed to the channel.
+Messages are streamed to clients as soon as they attach to a channel, as long as they have the `subscribe` [capability](/docs/platform/auth/capabilities) for it. This is independent of whether or not they have subscribed to the channel.
 
 Subscribing to a channel only registers a listener, or function, client-side that is called each time a message is received. This means that Ably is unaware of whether or not a client is subscribed to a channel.
 
@@ -392,7 +396,7 @@ Subscribing to events server-side using the pub-sub pattern can be disadvantageo
 
 Subscription filters enable you to subscribe to a channel and only receive messages that satisfy a filter expression.
 
-Messages are streamed to clients as soon as they [attach](/docs/channels/states#attach) to a channel, if they have the `subscribe` [capability](/docs/auth/capabilities) for it. Subscription filters apply server-side filtering to messages, meaning that a client will only ever receive the messages that they subscribe to.
+Messages are streamed to clients as soon as they [attach](/docs/channels/states#attach) to a channel, if they have the `subscribe` [capability](/docs/platform/auth/capabilities) for it. Subscription filters apply server-side filtering to messages, meaning that a client will only ever receive the messages that they subscribe to.
 
 Subscription filters are currently in preview status.
 
@@ -687,7 +691,7 @@ await pubChannel.publish({
 
 #### Subscription filter capabilities <a id="filter-capabilities"/>
 
-Clients require the subscribe [capability](/docs/auth/capabilities) for one of the following resources in order to receive messages from a subscription filter:
+Clients require the subscribe [capability](/docs/platform/auth/capabilities) for one of the following resources in order to receive messages from a subscription filter:
 
 * `[filter]<channel name>`
 * `[*]<channel name>`
@@ -1151,7 +1155,7 @@ You can use the REST interface of an Ably SDK to publish messages on behalf of a
 
 To publish on behalf of a realtime connection, the REST publisher requires the [`connectionKey`](/docs/api/realtime-sdk/connection#key) of the realtime client. The `connectionKey` is a secret of the client unless explicitly shared. The REST publisher can then set the `connectionKey` [in the root of the published message](/docs/api/rest-sdk/messages#connection-key).
 
-If the realtime connection is [identified](/docs/auth/identified-clients) by being bound to a `clientId`, then the REST publish must include that same `clientId`. This can be included in [the message itself](/docs/api/rest-sdk/messages#client-id) to apply to only that message, in the case that the REST client is able to assume any `clientId`, or using a REST client bound to that specific `clientId`.
+If the realtime connection is [identified](/docs/platform/auth/identified-clients) by being bound to a `clientId`, then the REST publish must include that same `clientId`. This can be included in [the message itself](/docs/api/rest-sdk/messages#client-id) to apply to only that message, in the case that the REST client is able to assume any `clientId`, or using a REST client bound to that specific `clientId`.
 
 The publish attempt will fail in the following scenarios:
 
diff --git a/src/pages/docs/pub-sub/index.mdx b/src/pages/docs/pub-sub/index.mdx
index 84f20a549d..c23d130a22 100644
--- a/src/pages/docs/pub-sub/index.mdx
+++ b/src/pages/docs/pub-sub/index.mdx
@@ -5,6 +5,10 @@ meta_description: "Get a channel, subscribe clients to it, and publish messages
 
 Ably Pub/Sub enables you to implement the publish-subscribe (pub-sub) pattern. Any number of publishers can send messages to a channel, and any number of subscribers can receive those messages. Publishers and subscribers are completely decoupled from one another.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 [Channels](/docs/channels) are used to separate messages into different topics. [Messages](/docs/messages) contain the data that a client is communicating, such as the contents of an individual chat message, or an event that has occurred, such as updated financial information. Whilst billions of messages may be delivered by Ably, clients receive only the messages on the channels they subscribe to.
 
 To get started with sending and receiving messages, all you need to do is:
@@ -115,6 +119,10 @@ Use the [`subscribe()`](/docs/api/realtime-sdk/channels#subscribe) method on a c
 
 The following is an example of subscribing to all messages on a channel:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
 const realtime = new Ably.Realtime('{{API_KEY}}');
@@ -291,7 +299,7 @@ _, err = channel.Subscribe(context.Background(), "myEvent", func(msg *ably.Messa
 
 ## Publish a message <a id="publish"/>
 
-Publishing messages to a channel is how clients communicate with one another. Any subscribers will receive published messages as long as they are subscribed and have the `subscribe` [capability](/docs/auth/capabilities) for that channel.
+Publishing messages to a channel is how clients communicate with one another. Any subscribers will receive published messages as long as they are subscribed and have the `subscribe` [capability](/docs/platform/auth/capabilities) for that channel.
 
 Publishing is an operation available to the realtime and REST interfaces of Pub/Sub SDKs. REST publishing is more efficient if you don't need to establish a persistent [connection](/docs/connect) to Ably, such as to subscribe to messages. For example, if you have a server publishing messages to channels that doesn't need to receive any updates from them.
 
diff --git a/src/pages/docs/push/configure/device.mdx b/src/pages/docs/push/configure/device.mdx
index d3a740ecb1..33e0de9097 100644
--- a/src/pages/docs/push/configure/device.mdx
+++ b/src/pages/docs/push/configure/device.mdx
@@ -494,6 +494,10 @@ Initialize the specific mobile device. You can achieve this by using either `App
 
 The `Initialize` method will create an instance of `RealtimeClient` or `RestClient`, which can be used to activate push notifications for the device by calling `client.Push.Activate()`. Activation is not guaranteed to happen immediately. The developer will be notified through the `ActivatedCallback`, which was passed to the `Initialize` method when setting up push notifications.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```csharp
 public override bool FinishedLaunching(UIApplication app, NSDictionary options)
diff --git a/src/pages/docs/push/index.mdx b/src/pages/docs/push/index.mdx
index 637909cff7..f71865fbcd 100644
--- a/src/pages/docs/push/index.mdx
+++ b/src/pages/docs/push/index.mdx
@@ -95,7 +95,7 @@ Each push target device or browser is associated with a unique `deviceId` and au
 
 * By utilizing an Ably token containing the device's or browser's `deviceId`.
 
-* By employing a standard [Ably key](/docs/auth/basic) or [Token](/docs/auth/token), with a `deviceIdentityToken`, a credential generated during registration to assert the device's or browser's identity, included in the request header.
+* By employing a standard [Ably key](/docs/platform/auth/basic) or [Token](/docs/platform/auth/token), with a `deviceIdentityToken`, a credential generated during registration to assert the device's or browser's identity, included in the request header.
 
 The service credential management is handled by the [Ably SDK](https://ably.com/docs/sdks), removing the need for the client application to manage device credentials unless accessing the [push admin API](/docs/api/realtime-sdk/push-admin) directly via HTTP.
 
diff --git a/src/pages/docs/spaces/authentication.mdx b/src/pages/docs/spaces/authentication.mdx
new file mode 100644
index 0000000000..6aded5529e
--- /dev/null
+++ b/src/pages/docs/spaces/authentication.mdx
@@ -0,0 +1,112 @@
+---
+title: Spaces authentication
+meta_description: "Configure authentication for Spaces applications with the required capabilities."
+---
+
+For comprehensive authentication guidance including server implementation, client patterns, and token lifecycle, see [Platform Authentication](/docs/platform/auth/token).
+
+This page covers Spaces-specific capabilities and space scoping.
+
+## Spaces capabilities
+
+Your tokens need specific capabilities depending on which Spaces features you use:
+
+| Feature | Required Capabilities |
+|---------|----------------------|
+| Avatar stack (member events) | `subscribe`, `presence` |
+| Member locations | `subscribe`, `presence` |
+| Live cursors | `publish`, `subscribe` |
+| Component locking | `subscribe`, `presence` |
+| **All Spaces features** | `publish`, `subscribe`, `presence`, `history` |
+
+## Space-scoped capabilities
+
+You can restrict tokens to specific spaces. Spaces use multiple channels for different features:
+
+<Code>
+```javascript
+// Server-side JWT with space-scoped capabilities
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+const ablyJwt = jwt.sign(
+  {
+    'x-ably-capability': JSON.stringify({
+      // Main space channel for presence and locations
+      'your-space': ['publish', 'subscribe', 'presence', 'history'],
+      // Cursors channel
+      'your-space::$cursors': ['publish', 'subscribe'],
+    }),
+    'x-ably-clientId': userId,
+  },
+  keySecret,
+  { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+);
+```
+
+```python
+# Server-side JWT with space-scoped capabilities
+import jwt
+import json
+import time
+import os
+
+key_name, key_secret = os.environ['ABLY_API_KEY'].split(':')
+
+now = int(time.time())
+ably_jwt = jwt.encode(
+    {
+        'iat': now,
+        'exp': now + 3600,
+        'x-ably-capability': json.dumps({
+            # Main space channel for presence and locations
+            'your-space': ['publish', 'subscribe', 'presence', 'history'],
+            # Cursors channel
+            'your-space::$cursors': ['publish', 'subscribe'],
+        }),
+        'x-ably-clientId': user_id,
+    },
+    key_secret,
+    algorithm='HS256',
+    headers={'kid': key_name}
+)
+```
+</Code>
+
+<Aside data-type='important'>
+If you use API key authentication on the client, any user can claim any `clientId`, undermining the collaborative features that Spaces provides. Always use [token authentication](/docs/platform/auth/token) in production.
+</Aside>
+
+## Client setup
+
+Use `authCallback` to fetch JWTs from your auth server:
+
+<Code>
+```javascript
+import Spaces from '@ably/spaces';
+import { Realtime } from 'ably';
+
+const client = new Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token');
+      const jwt = await response.text();
+      callback(null, jwt);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
+
+const spaces = new Spaces(client);
+```
+</Code>
+
+See [token authentication](/docs/platform/auth/token#auth-callback) for complete examples in all languages.
+
+## Further reading
+
+- [Token authentication](/docs/platform/auth/token) - Complete token authentication guide
+- [Capabilities](/docs/platform/auth/capabilities) - Fine-grained permission control
+- [Identified clients](/docs/platform/auth/identified-clients) - Assigning trusted client identities
diff --git a/src/pages/docs/spaces/avatar.mdx b/src/pages/docs/spaces/avatar.mdx
index fd148ec7df..c774009517 100644
--- a/src/pages/docs/spaces/avatar.mdx
+++ b/src/pages/docs/spaces/avatar.mdx
@@ -96,7 +96,7 @@ The following are the properties of a member event payload:
 
 | Property | Description| Type |
 | -------- | ---------- | ---- |
-| clientId | The [client identifier](/docs/auth/identified-clients) for the member. | String |
+| clientId | The [client identifier](/docs/platform/auth/identified-clients) for the member. | String |
 | connectionId | The unique identifier of the member's [connection](/docs/connect). | String |
 | isConnected | Whether the member is connected to Ably or not. | Boolean |
 | profileData | The optional [profile data](#profile-data) associated with the member. | Object |
diff --git a/src/pages/docs/spaces/cursors.mdx b/src/pages/docs/spaces/cursors.mdx
index 2b3e30f231..84670d55fd 100644
--- a/src/pages/docs/spaces/cursors.mdx
+++ b/src/pages/docs/spaces/cursors.mdx
@@ -90,7 +90,7 @@ The following are the properties of a cursor event payload:
 | Property | Description | Type |
 | -------- | ----------- | ---- |
 | connectionId | The unique identifier of the member's [connection](/docs/connect). | String |
-| clientId | The [client identifier](/docs/auth/identified-clients) for the member. | String |
+| clientId | The [client identifier](/docs/platform/auth/identified-clients) for the member. | String |
 | position | An object containing the position of a member's cursor. | Object |
 | position.x | The position of the member's cursor on the X-axis. | Number |
 | position.y | The position of the member's cursor on the Y-axis. | Number |
diff --git a/src/pages/docs/spaces/index.mdx b/src/pages/docs/spaces/index.mdx
index 6c4392dc7d..e6ace7342b 100644
--- a/src/pages/docs/spaces/index.mdx
+++ b/src/pages/docs/spaces/index.mdx
@@ -31,7 +31,7 @@ Whether you're adding realtime collaborative capabilities to an existing applica
 
 There are several benefits provided by the fact that the Spaces SDK is built on top of the Ably JavaScript SDK:
 
-* [Authentication](/docs/auth) and [connection management](/docs/connect) are handled by the underlying SDK.
+* [Authentication](/docs/platform/auth) and [connection management](/docs/connect) are handled by the underlying SDK.
 * You can use the Ably JavaScript SDK to extend your application's functionality further with [Pub/Sub](/docs/basics).
 
 The following are a selection of additional features that can be built using Ably Pub/Sub to further enhance your collaborative applications:
diff --git a/src/pages/docs/spaces/locations.mdx b/src/pages/docs/spaces/locations.mdx
index e55ff8af5a..0824d462b3 100644
--- a/src/pages/docs/spaces/locations.mdx
+++ b/src/pages/docs/spaces/locations.mdx
@@ -81,7 +81,7 @@ The following are the properties of a location event payload:
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
-| member.clientId| The [client identifier](/docs/auth/identified-clients) for the member. | String |
+| member.clientId| The [client identifier](/docs/platform/auth/identified-clients) for the member. | String |
 | member.connectionId| The unique identifier of the member's [connection](/docs/connect). | String |
 | member.isConnected | Whether the member is connected to Ably or not.| Boolean |
 | member.lastEvent.name| The most recent event emitted by the member. Will be one of `enter`, `update`, `present`, or `leave`. | String |
diff --git a/src/pages/docs/spaces/locking.mdx b/src/pages/docs/spaces/locking.mdx
index 3f88a6c094..b0d0004734 100644
--- a/src/pages/docs/spaces/locking.mdx
+++ b/src/pages/docs/spaces/locking.mdx
@@ -154,7 +154,7 @@ The following are the properties of a lock event payload:
 | timestamp| The timestamp of the lock event. | Number |
 | attributes | The optional attributes of the lock, such as the ID of the component it relates to. | Object |
 | reason | If set, gives the reason for `status`. Successful lock requests do not set a `reason`. | ErrorInfo |
-| member.clientId| The [client identifier](/docs/auth/identified-clients) for the member. | String |
+| member.clientId| The [client identifier](/docs/platform/auth/identified-clients) for the member. | String |
 | member.connectionId| The unique identifier of the member's [connection](/docs/connect). | String |
 | member.isConnected | Whether the member is connected to Ably or not. | Boolean |
 | member.lastEvent.name| The most recent event emitted by the member. Will be one of `enter`, `update`, `present`, or `leave`. | String |
diff --git a/src/pages/docs/spaces/react.mdx b/src/pages/docs/spaces/react.mdx
index d6e61821bd..c12599f773 100644
--- a/src/pages/docs/spaces/react.mdx
+++ b/src/pages/docs/spaces/react.mdx
@@ -41,12 +41,12 @@ React version 16.8.0 or above is required.
 
 ## Authenticate <a id="authenticate"/>
 
-An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
+An [API key](/docs/platform/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/platform/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/platform/auth/token).
 
 [Sign up](https://ably.com/sign-up) to Ably to create an API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API programmatically.
 
 <Aside data-type='important'>
-The examples use [basic authentication](/docs/auth/basic) to demonstrate usage for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/auth/token).
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate usage for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
 </Aside>
 
 ## Usage <a id="usage"/>
@@ -55,6 +55,10 @@ The examples use [basic authentication](/docs/auth/basic) to demonstrate usage f
 
 Use the `SpacesProvider` component to connect to Ably. The `SpacesProvider` should wrap every component that needs to access Spaces.
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```react
 import { Realtime } from "ably";
diff --git a/src/pages/docs/spaces/setup.mdx b/src/pages/docs/spaces/setup.mdx
index 5fc928839d..498bbb561d 100644
--- a/src/pages/docs/spaces/setup.mdx
+++ b/src/pages/docs/spaces/setup.mdx
@@ -7,15 +7,18 @@ Use these instructions to install, authenticate and instantiate the Spaces SDK.
 
 ## Authenticate <a id="authenticate"/>
 
-An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token).
-
 <Aside data-type='important'>
-The examples use [basic authentication](/docs/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/auth/token).
+**Security requirement:** Client-side applications must use [JWT token authentication](/docs/platform/auth/token#choosing-jwt). Never expose your API key in client-side code.
 </Aside>
 
-[Sign up](https://ably.com/sign-up) to Ably to create an API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API programmatically.
+Spaces requires an authenticated client with a `clientId` to identify users. The recommended approach is:
+
+1. **Client-side apps** (browsers, mobile apps): Use [JWT authentication](/docs/platform/auth/token#choosing-jwt) with `authCallback` to fetch JWTs from your server
+2. **Server-side apps** (Node.js, Python, etc.): Use your API key directly
 
-API keys and tokens have a set of capabilities assigned to them that specify which operations, such as `subscribe` or `publish` can be performed on which resources. To use the Spaces SDK, the API key requires the following [capabilities](/docs/auth/capabilities):
+[Sign up](https://ably.com/sign-up) to Ably to create an API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API programmatically. Your server will use this key to issue tokens to clients.
+
+API keys and tokens have a set of capabilities assigned to them that specify which operations, such as `subscribe` or `publish` can be performed on which resources. To use the Spaces SDK, the API key requires the following [capabilities](/docs/platform/auth/capabilities):
 
 * Publish
 * Subscribe
@@ -64,21 +67,126 @@ Reference the Ably JavaScript SDK and the Spaces SDK within the `<head>` of your
 
 ## Instantiate <a id="instantiate"/>
 
-Instantiate a realtime client using the Ably JavaScript SDK and pass the generated client into the Spaces constructor:
+Instantiate a realtime client using the Ably JavaScript SDK and pass the generated client into the Spaces constructor.
+
+### Client-side authentication (recommended) <a id="client-side-auth"/>
+
+Use token authentication for browsers and mobile apps. Your auth server endpoint validates the user and returns an Ably token with the appropriate `clientId`:
 
 <Code>
 ```javascript
+// Client-side: Token authentication (recommended for browsers)
+
 // If installing via NPM
-const client = new Realtime({key: "<API-key>", clientId: "<client-ID>"});
+const client = new Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token');
+      const token = await response.text();
+      callback(null, token);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
 const spaces = new Spaces(client);
 
 // If installing via CDN
-const client = new Ably.Realtime({key: "<API-key>", clientId: "<client-ID>"});
+const client = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-token');
+      const token = await response.text();
+      callback(null, token);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
+const spaces = new Spaces(client);
+```
+</Code>
+
+Your auth server endpoint (`/api/ably-token`) should authenticate the user and return a token with the user's `clientId`. See the [token authentication](/docs/platform/auth/token) documentation for server implementation examples.
+
+### Server-side authentication <a id="server-side-auth"/>
+
+For server-side applications or local development, you can use an API key directly:
+
+<Code>
+```javascript
+// Server-side only: API key authentication
+// WARNING: Never use this in client-side code (browsers, mobile apps)
+const client = new Realtime({
+  key: process.env.ABLY_API_KEY,
+  clientId: 'server-process-1'
+});
+const spaces = new Spaces(client);
+```
+</Code>
+
+A [`ClientOptions`](/docs/api/realtime-sdk#client-options) object may be passed to the Ably JavaScript SDK to further customize the connection. When using token authentication, the `clientId` is set by your auth server. When using API key authentication server-side, you must provide a `clientId` so that the client is [identified](/docs/platform/auth/identified-clients).
+
+### Using Ably JWT (alternative) <a id="jwt-auth"/>
+
+If you have existing JWT-based authentication infrastructure (Auth0, Firebase, Cognito, or custom), you can create Ably JWTs directly without using the Ably SDK on your server:
+
+**Server (no Ably SDK required):**
+
+<Code>
+```javascript
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+app.get('/api/ably-jwt', async (req, res) => {
+  // Your existing auth middleware validates the user
+  const userId = req.user.id;
+
+  const ablyJwt = jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({
+        '*': ['publish', 'subscribe', 'presence', 'history'],
+      }),
+      'x-ably-clientId': userId,
+    },
+    keySecret,
+    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
+  );
+
+  res.send(ablyJwt);
+});
+```
+</Code>
+
+**Client:**
+
+<Code>
+```javascript
+const client = new Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/ably-jwt', {
+        headers: { 'Authorization': `Bearer ${yourAppJwt}` },
+      });
+      const jwt = await response.text();
+      callback(null, jwt);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
 const spaces = new Spaces(client);
 ```
 </Code>
 
-A [`ClientOptions`](/docs/api/realtime-sdk#client-options) object may be passed to the Ably JavaScript SDK to further customize the connection, however at a minimum you must set your API key and provide a `clientId` so that the client is [identified](/docs/auth/identified-clients).
+**Why choose JWT for Spaces?**
+- No Ably SDK required on your server
+- Integrates with existing Auth0/Firebase/Cognito flows
+- Supports [channel-scoped claims](/docs/platform/auth/capabilities#custom-restrictions) for user metadata
+- Eliminates client round-trip to Ably
+
+See [Choosing a token mechanism](/docs/platform/auth/token#choosing) for detailed guidance on when to use JWT vs TokenRequest.
 
 <Aside data-type='note'>
 Only the promises version of the Ably JavaScript is supported when using Spaces, not the callback version.
diff --git a/src/pages/docs/spaces/space.mdx b/src/pages/docs/spaces/space.mdx
index e544e70d21..107e1ebb66 100644
--- a/src/pages/docs/spaces/space.mdx
+++ b/src/pages/docs/spaces/space.mdx
@@ -187,7 +187,7 @@ The following are the properties of an individual `member` within a space event
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
-| clientId | The [client identifier](/docs/auth/identified-clients) for the member. | String |
+| clientId | The [client identifier](/docs/platform/auth/identified-clients) for the member. | String |
 | connectionId | The unique identifier of the member's [connection](/docs/connect). | String |
 | isConnected | Whether the member is connected to Ably or not. | Boolean |
 | profileData | The optional [profile data](#profile-data) associated with the member. | Object |
diff --git a/src/pages/docs/storage-history/history.mdx b/src/pages/docs/storage-history/history.mdx
index 4ad96cf087..d102158a0c 100644
--- a/src/pages/docs/storage-history/history.mdx
+++ b/src/pages/docs/storage-history/history.mdx
@@ -56,6 +56,10 @@ This pattern is commonly used when implementing channel sharding, where related
 
 This example retrieves the latest message sent on a channel:
 
+<Aside data-type='important'>
+The examples use [basic authentication](/docs/platform/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/platform/auth/token).
+</Aside>
+
 <Code>
 ```realtime_javascript
 const realtime = new Ably.Realtime('{{API_KEY}}');