Move auth docs to /docs/platform/auth and update navigation

- Move 8 auth MDX files from /docs/auth/ to /docs/platform/auth/
- Add redirect_from entries for all old /docs/auth/* paths
- Add Authentication section to Platform nav (with nested Token auth)
- Remove Authentication section from Pub/Sub nav
- Update cross-references within auth files to new paths
- Fix relative image paths for new directory depth

Author: umair-ably

src/data/nav/platform.ts

@@ -331,6 +331,50 @@ export default {
         },
       ],
     },
+    {
+      name: 'Authentication',
+      pages: [
+        {
+          name: 'Overview',
+          link: '/docs/platform/auth',
+          index: true,
+        },
+        {
+          name: 'Basic auth',
+          link: '/docs/platform/auth/basic',
+        },
+        {
+          name: 'Token auth',
+          pages: [
+            {
+              name: 'Overview',
+              link: '/docs/platform/auth/token',
+              index: true,
+            },
+            {
+              name: 'JWTs',
+              link: '/docs/platform/auth/token/jwt',
+            },
+            {
+              name: 'Ably Tokens',
+              link: '/docs/platform/auth/token/ably-tokens',
+            },
+          ],
+        },
+        {
+          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: [

src/data/nav/pubsub.ts

@@ -83,50 +83,6 @@ export default {
         },
       ],
     },
-    {
-      name: 'Authentication',
-      pages: [
-        {
-          name: 'Overview',
-          link: '/docs/auth',
-          index: true,
-        },
-        {
-          name: 'Basic auth',
-          link: '/docs/auth/basic',
-        },
-        {
-          name: 'Token auth',
-          pages: [
-            {
-              name: 'Overview',
-              link: '/docs/auth/token',
-              index: true,
-            },
-            {
-              name: 'JWTs',
-              link: '/docs/auth/token/jwt',
-            },
-            {
-              name: 'Ably Tokens',
-              link: '/docs/auth/token/ably-tokens',
-            },
-          ],
-        },
-        {
-          name: 'Token revocation',
-          link: '/docs/auth/revocation',
-        },
-        {
-          name: 'Identified clients',
-          link: '/docs/auth/identified-clients',
-        },
-        {
-          name: 'Capabilities',
-          link: '/docs/auth/capabilities',
-        },
-      ],
-    },
     {
       name: 'Connections',
       pages: [

src/pages/docs/auth/basic.mdx src/pages/docs/platform/auth/basic.mdxsrc/pages/docs/auth/basic.mdx renamed to 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.
@@ -115,14 +117,14 @@ $rest = new Ably\AblyRest(['key' => '{{API_KEY}}']);
 
 The process used by Ably SDKs to authenticate with Ably using basic authentication is illustrated in the following diagram:
 
-![Basic authentication process diagram](../../../images/content/diagrams/Ably-API-Auth1.png)
+![Basic authentication process diagram](../../../../images/content/diagrams/Ably-API-Auth1.png)
 
 ## When to use basic auth <a id="when"/>
 
 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'>

src/pages/docs/auth/capabilities.mdx …ages/docs/platform/auth/capabilities.mdxsrc/pages/docs/auth/capabilities.mdx renamed to src/pages/docs/platform/auth/capabilities.mdx src/pages/docs/auth/capabilities.mdx renamed to src/pages/docs/platform/auth/capabilities.mdx

@@ -1,23 +1,25 @@
 ---
 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"/>
 
 <Aside data-type='important'>
 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.
 
@@ -358,7 +360,7 @@ Note that a successful token request doesn't guarantee all requested capabilitie
 
 #### 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/ably-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/ably-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.
 
@@ -435,7 +437,7 @@ if err != nil {
 
 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/ably-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/ably-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
@@ -533,7 +535,7 @@ if err != nil {
 
 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/ably-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/ably-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
@@ -595,15 +597,15 @@ if err != nil {
 
 #### Ably JWT capability determination <a id="ably-jwt"/>
 
-Capabilities are determined for [JWTs](/docs/auth/token/jwt) in the following way:
+Capabilities are determined for [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.
 
 ## Channel-scoped user claims <a id="custom-restrictions"/>
 
-JWTs can contain channel-scoped user claims for trusted metadata that other clients can read. See [JWT authentication — channel-scoped claims](/docs/auth/token/jwt#channel-claims) for details and examples.
+JWTs can contain channel-scoped user claims for trusted metadata that other clients can read. See [JWT authentication — channel-scoped claims](/docs/platform/auth/token/jwt#channel-claims) for details and examples.
 
 ## Per-connection publish rate limits <a id="jwt-limits"/>
 
-JWTs can specify per-connection publish rate limits to restrict how many messages a client can send. See [JWT authentication — rate limits](/docs/auth/token/jwt#rate-limits) for details and examples.
+JWTs can specify per-connection publish rate limits to restrict how many messages a client can send. See [JWT authentication — rate limits](/docs/platform/auth/token/jwt#rate-limits) for details and examples.

…c/pages/docs/auth/identified-clients.mdx …ocs/platform/auth/identified-clients.mdxsrc/pages/docs/auth/identified-clients.mdx renamed to src/pages/docs/platform/auth/identified-clients.mdx src/pages/docs/auth/identified-clients.mdx renamed to src/pages/docs/platform/auth/identified-clients.mdx

@@ -1,6 +1,8 @@
 ---
 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.
@@ -33,18 +35,18 @@ There are three different ways a client can be identified with using a `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.
+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/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.
+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/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`.
+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`.
 
@@ -56,7 +58,7 @@ To set a `clientId` in a JWT, include the `x-ably-clientId` claim in the JWT pay
 | --- | --- |
 | `x-ably-clientId` | The `clientId` to assign to the client (for example, `user-123`). |
 
-See [JWT authentication](/docs/auth/token/jwt#scenario-standard) for complete server and client examples in all supported languages.
+See [JWT authentication](/docs/platform/auth/token/jwt#scenario-standard) for complete server and client examples in all supported languages.
 
 #### Using TokenRequest <a id="tokenrequest-clientid"/>
 
@@ -129,8 +131,8 @@ final tokenRequest = rest.auth.createTokenRequest(
 
 ### 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.
+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/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.
+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.