[FTF-468] Auth Phase 2

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

@@ -85,47 +85,7 @@ 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',
-        },
-      ],
+      link: '/docs/authentication',
     },
     {
       name: 'Connections',

src/pages/docs/ai-transport/index.mdx

@@ -165,7 +165,7 @@ It also puts you in control of how you manage your application when there aren't
 
 ### Enterprise controls <a id="enterprise"/>
 
-Ably's platform provides [integrations](/docs/platform/integrations) and functionality to ensure that your applications always exceed the requirements of enterprise environments. Whether that's [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/auth/identified-clients) or [fine-grained authorization](/docs/auth/capabilities).
+Ably's platform provides [integrations](/docs/platform/integrations) and functionality to ensure that your applications always exceed the requirements of enterprise environments. Whether that's [message auditing](/docs/platform/integrations/streaming), [client identification](/docs/platform/auth/identified-clients) or [fine-grained authorization](/docs/platform/auth/capabilities).
 
 ## Examples
 

src/pages/docs/ai-transport/messaging/citations.mdx

@@ -306,7 +306,7 @@ The `multiple.v1` summary groups counts by the annotation `name`, with totals an
 ```
 </Code>
 
-When agents publish citations with a [`clientId`](/docs/auth/identified-clients), summaries include a per-client count showing how many citations each agent contributed. Citations published by [unidentified](/docs/auth/identified-clients#unidentified) clients are counted in the `totalUnidentified` field.
+When agents publish citations with a [`clientId`](/docs/platform/auth/identified-clients), summaries include a per-client count showing how many citations each agent contributed. Citations published by [unidentified](/docs/platform/auth/identified-clients#unidentified) clients are counted in the `totalUnidentified` field.
 
 <Aside data-type="note">
 The `clipped` field indicates whether the summary was truncated due to size limits. This only occurs when a large number of clients with distinct `clientId`s publish annotations. See [large summaries](/docs/messages/annotations#large-summaries) for more information.

src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx

@@ -330,7 +330,7 @@ channel.subscribe("approval-response", message -> {
 
 ### Verify by role <a id="verify-role"/>
 
-Use [user claims](/docs/auth/capabilities#custom-restrictions-on-channels-) to embed roles directly in the JWT for role-based access control (RBAC). This approach is useful when permissions are role-based rather than user-specific, allowing you to make authorization decisions based on the user's role without looking up individual user permissions.
+Use [user claims](/docs/platform/auth/capabilities#custom-restrictions-on-channels-) to embed roles directly in the JWT for role-based access control (RBAC). This approach is useful when permissions are role-based rather than user-specific, allowing you to make authorization decisions based on the user's role without looking up individual user permissions.
 
 <Aside data-type="note">
 This approach uses [authenticated claims for users](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-claims) to embed custom claims in JWTs that represent user roles or attributes.

src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx

@@ -17,9 +17,9 @@ In decoupled architectures, identity serves several critical purposes:
 
 ## Authenticating users <a id="authenticating"/>
 
-Use [token authentication](/docs/auth/token) to authenticate users securely. Your authentication server generates a token that is signed with the secret part of your Ably API key. Clients use this token to connect to Ably, and the token signature ensures it cannot be tampered with.
+Use [token authentication](/docs/platform/auth/token) to authenticate users securely. Your authentication server generates a token that is signed with the secret part of your Ably API key. Clients use this token to connect to Ably, and the token signature ensures it cannot be tampered with.
 
-The following examples use [JWT authentication](/docs/auth/token#jwt) for its simplicity and standard tooling support. For other approaches, see [token authentication](/docs/auth/token).
+The following examples use [JWT authentication](/docs/platform/auth/token#jwt) for its simplicity and standard tooling support. For other approaches, see [token authentication](/docs/platform/auth/token).
 
 Create a server endpoint that generates signed JWTs after verifying user authentication:
 
@@ -179,10 +179,10 @@ The `authenticateUser` middleware in this example is for demonstration purposes
 
 The JWT is signed with the secret part of your Ably API key using [HMAC-SHA-256](https://datatracker.ietf.org/doc/html/rfc4868). This example does not embed any claims in the JWT payload, so by default the token inherits the capabilities of the Ably API key used to sign the token.
 
-Configure your client to obtain a signed JWT from your server endpoint using an [`authCallback`](/docs/auth/token#auth-callback). The client obtains a signed JWT from the callback and uses it to authenticate requests to Ably. The client automatically makes a request for a new token before it expires.
+Configure your client to obtain a signed JWT from your server endpoint using an [`authCallback`](/docs/platform/auth/token#auth-callback). The client obtains a signed JWT from the callback and uses it to authenticate requests to Ably. The client automatically makes a request for a new token before it expires.
 
 <Aside data-type="important">
-Never include your Ably API key in client code. Instead, always authenticate clients using [token auth](/docs/auth/token).
+Never include your Ably API key in client code. Instead, always authenticate clients using [token auth](/docs/platform/auth/token).
 </Aside>
 
 <Code>
@@ -244,7 +244,7 @@ ably.connection.on(ConnectionState.connected, state -> {
 
 ## Authenticating agents <a id="authenticating-agents"/>
 
-Agents typically run on servers in trusted environments where API keys can be securely stored. Use [API key authentication](/docs/auth#basic-authentication) to authenticate agents directly with Ably.
+Agents typically run on servers in trusted environments where API keys can be securely stored. Use [API key authentication](/docs/platform/auth#basic-authentication) to authenticate agents directly with Ably.
 
 <Code>
 ```javascript
@@ -287,12 +287,12 @@ Only use API key authentication in server-side code. Never include your Ably API
 </Aside>
 
 <Aside data-type="note">
-Agents can also authenticate using [token authentication](/docs/auth/token), which is useful when agents run in environments where API keys should not be stored or when agents need dynamic capabilities that change based on runtime conditions.
+Agents can also authenticate using [token authentication](/docs/platform/auth/token), which is useful when agents run in environments where API keys should not be stored or when agents need dynamic capabilities that change based on runtime conditions.
 </Aside>
 
 ## Specifying capabilities <a id="capabilities"/>
 
-Use [capabilities](/docs/auth/capabilities) to specify which operations clients can perform on which channels. This applies to both users and agents, allowing you to enforce fine-grained permissions.
+Use [capabilities](/docs/platform/auth/capabilities) to specify which operations clients can perform on which channels. This applies to both users and agents, allowing you to enforce fine-grained permissions.
 
 ### User capabilities <a id="user-capabilities"/>
 
@@ -409,7 +409,7 @@ announcementsChannel.subscribe(msg -> System.out.println(msg)); // succeeds
 </Code>
 
 <Aside data-type="note">
-Ably recommends using token authentication with short-lived tokens and minimal capabilities required for each user to limit the window of exposure if a token is compromised. For more information, see [When to use token auth](/docs/auth/token#when).
+Ably recommends using token authentication with short-lived tokens and minimal capabilities required for each user to limit the window of exposure if a token is compromised. For more information, see [When to use token auth](/docs/platform/auth/token#when).
 </Aside>
 
 ### Agent capabilities <a id="agent-capabilities"/>
@@ -479,12 +479,12 @@ Following the principle of least privilege, provision API keys with the minimum
 
 Use the [`clientId`](/docs/messages#properties) to identify the user or agent that published a message. The method for setting `clientId` depends on your authentication approach:
 
-- When using [basic authentication](/docs/auth/identified-clients#basic), specify the `clientId` directly in the client options when instantiating the client instance.
-- When using [token authentication](/docs/auth/identified-clients#token), specify an explicit `clientId` when issuing the token.
+- When using [basic authentication](/docs/platform/auth/identified-clients#basic), specify the `clientId` directly in the client options when instantiating the client instance.
+- When using [token authentication](/docs/platform/auth/identified-clients#token), specify an explicit `clientId` when issuing the token.
 
 ### User identity <a id="user-identity"/>
 
-Users typically authenticate using [token authentication](/docs/auth/identified-clients#token). Add the [`x-ably-clientId`](/docs/api/realtime-sdk/authentication#ably-jwt) claim to your JWT to establish a verified identity for each user client. This identity appears as the [`clientId`](/docs/messages#properties) in all messages the user publishes, and subscribers can trust this identity because only your server can issue JWTs with specific `clientId` values.
+Users typically authenticate using [token authentication](/docs/platform/auth/identified-clients#token). Add the [`x-ably-clientId`](/docs/api/realtime-sdk/authentication#ably-jwt) claim to your JWT to establish a verified identity for each user client. This identity appears as the [`clientId`](/docs/messages#properties) in all messages the user publishes, and subscribers can trust this identity because only your server can issue JWTs with specific `clientId` values.
 
 As with all clients, the method for setting `clientId` depends on your [authentication approach](#identity).
 
@@ -608,7 +608,7 @@ The `clientId` in the message can be trusted, so agents can use this identity to
 
 ### Agent identity <a id="agent-identity"/>
 
-Agent code typically runs in a trusted environment, so you can use [basic authentication](/docs/auth/identified-clients#basic) and directly specify the `clientId` when instantiating the agent client. This identity appears as the [`clientId`](/docs/messages#properties) in all messages the agent publishes, allowing subscribers to identify the agent which published a message.
+Agent code typically runs in a trusted environment, so you can use [basic authentication](/docs/platform/auth/identified-clients#basic) and directly specify the `clientId` when instantiating the agent client. This identity appears as the [`clientId`](/docs/messages#properties) in all messages the agent publishes, allowing subscribers to identify the agent which published a message.
 
 <Code>
 ```javascript
@@ -681,7 +681,7 @@ channel.subscribe(message -> {
 </Code>
 
 <Aside data-type="note">
-Agents can also authenticate using [token authentication](/docs/auth/token), which is useful when agents run in environments where API keys cannot be accessed securely or when agents need [dynamic capabilities](/docs/auth/token#dynamic-channel-access-control).
+Agents can also authenticate using [token authentication](/docs/platform/auth/token), which is useful when agents run in environments where API keys cannot be accessed securely or when agents need [dynamic capabilities](/docs/platform/auth/token#dynamic-channel-access-control).
 </Aside>
 
 ## Adding roles and attributes <a id="roles-attributes"/>
@@ -690,7 +690,7 @@ Embed custom roles and attributes in messages to enable role-based access contro
 
 ### User claims <a id="user-claims"/>
 
-Use [authenticated claims for users](/docs/auth/capabilities#custom-restrictions-on-channels-) to embed custom claims in JWTs that represent user roles or attributes.
+Use [authenticated claims for users](/docs/platform/auth/capabilities#custom-restrictions-on-channels-) to embed custom claims in JWTs that represent user roles or attributes.
 
 Add claims with names matching the `ably.channel.*` pattern to your JWT to specify user claims for specific channels. Claims can be scoped to individual channels or to [namespaces](/docs/channels#namespaces) of channels. The most specific user claim matching the channel is automatically included under `extras.userClaim` in all messages the client publishes.
 

src/pages/docs/ai-transport/sessions-identity/online-status.mdx

@@ -26,7 +26,7 @@ For details on authenticating users and agents and setting the `clientId`, see [
 You have flexibility in when to enter presence. For example, an agent might choose to appear as online only while processing a specific task, or remain present for the duration of the entire session. Users typically enter presence when they connect to a session and remain present until they disconnect.
 
 <Aside data-type="note">
-Clients require the [`presence`](/docs/auth/capabilities) capability on the channel to participate in presence.
+Clients require the [`presence`](/docs/platform/auth/capabilities) capability on the channel to participate in presence.
 </Aside>
 
 For example, a user client can enter presence when joining a session:
@@ -98,7 +98,7 @@ channel.presence.enter(data);
 
 ### Going online from multiple devices <a id="multiple-devices"/>
 
-A single user can be present on a channel from multiple devices simultaneously. Ably tracks each connection separately using a unique [`connectionId`](/docs/connect#connection-ids), while maintaining the same [`clientId`](/docs/auth/identified-clients#assign) across all connections.
+A single user can be present on a channel from multiple devices simultaneously. Ably tracks each connection separately using a unique [`connectionId`](/docs/connect#connection-ids), while maintaining the same [`clientId`](/docs/platform/auth/identified-clients#assign) across all connections.
 
 When a user connects from multiple devices, each device enters presence independently. All connections share the same `clientId` but have different `connectionId` values.
 
@@ -360,7 +360,7 @@ AblyRealtime ably = new AblyRealtime(options);
 Participants in a session can query the current presence set or subscribe to presence events to see who else is online and react to changes in realtime. Users might want to see which agents are processing work, while agents might want to detect when specific users are offline to pause or cancel work.
 
 <Aside data-type="note">
-Clients require the `subscribe` [capability](/docs/auth/capabilities) on the channel to retrieve the presence set and subscribe to presence events.
+Clients require the `subscribe` [capability](/docs/platform/auth/capabilities) on the channel to retrieve the presence set and subscribe to presence events.
 </Aside>
 
 ### Retrieving current presence members <a id="get-members"/>

src/pages/docs/ai-transport/sessions-identity/push-notifications.mdx

@@ -31,7 +31,7 @@ Push notification setup is platform-specific. See the following guides to config
 </Aside>
 
 <Aside data-type="note">
-To send push notifications to a specific user's devices rather than to channel subscribers, the agent's token requires the `push-admin` [capability](/docs/auth/capabilities). This enables direct publishing via the Push Admin API.
+To send push notifications to a specific user's devices rather than to channel subscribers, the agent's token requires the `push-admin` [capability](/docs/platform/auth/capabilities). This enables direct publishing via the Push Admin API.
 </Aside>
 
 ## Opt-in patterns <a id="opt-in"/>

src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx

@@ -59,7 +59,7 @@ Ably provides access to channel message history, enabling agents to retrieve any
 When an agent resumes, it needs to retrieve messages published while it was offline. Use [channel history](/docs/storage-history/history) with the [`untilAttach` option](/docs/storage-history/history#continuous-history) to catch up on historical messages while preserving continuity with live message delivery.
 
 <Aside data-type="note">
-Clients require the [`history`](/docs/auth/capabilities) capability on the channel to retrieve message history.
+Clients require the [`history`](/docs/platform/auth/capabilities) capability on the channel to retrieve message history.
 </Aside>
 
 #### Persisted session state

src/pages/docs/ai-transport/token-streaming/message-per-response.mdx

@@ -41,7 +41,7 @@ To enable the channel rule:
 
 The examples on this page use the `ai:` namespace prefix, which assumes you have configured the rule for `ai`.
 
-Your token or API key needs the following [capabilities](/docs/auth/capabilities) on the channel:
+Your token or API key needs the following [capabilities](/docs/platform/auth/capabilities) on the channel:
 
 | Capability | Purpose |
 | --- | --- |