DRAFT - [EDU-2066] - Add Auth section to Platform

src/data/nav/platform.ts

@@ -18,6 +18,28 @@ export default {
         },
       ],
     },
+    {
+      name: 'Authentication',
+      pages: [
+        {
+          name: 'Overview',
+          link: '/docs/platform/auth',
+          index: true,
+        },
+        {
+          name: 'Authentication methods',
+          link: '/docs/platform/auth/authentication',
+        },
+        {
+          name: 'Identified clients & capabilities',
+          link: '/docs/platform/auth/capabilities',
+        },
+        {
+          name: 'Token Revocation',
+          link: '/docs/platform/auth/revocation',
+        },
+      ],
+    },
     {
       name: 'Architecture',
       pages: [

src/data/nav/pubsub.ts

@@ -101,28 +101,20 @@ export default {
       pages: [
         {
           name: 'Overview',
-          link: '/docs/auth',
+          link: '/docs/platform/auth',
           index: true,
         },
         {
-          name: 'Basic auth',
-          link: '/docs/auth/basic',
+          name: 'Authentication Methods',
+          link: '/docs/platform/auth/authentication',
         },
         {
-          name: 'Token auth',
-          link: '/docs/auth/token',
+          name: 'Permissions & Capabilities',
+          link: '/docs/platform/auth/capabilities',
         },
         {
-          name: 'Token revocation',
-          link: '/docs/auth/revocation',
-        },
-        {
-          name: 'Identified clients',
-          link: '/docs/auth/identified-clients',
-        },
-        {
-          name: 'Capabilities',
-          link: '/docs/auth/capabilities',
+          name: 'Token Revocation',
+          link: '/docs/platform/auth/revocation',
         },
       ],
     },

src/pages/docs/auth/capabilities.mdx

@@ -7,7 +7,7 @@ API keys and Ably-compatible tokens, have a set of capabilities assigned to them
 
 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. 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. See [selecting an authentication mechanism](/docs/platform/auth/authentication#how-to-choose-authentication-method) to understand why token authentication is the preferred option in most scenarios.
 
 ## Resource names and wildcards <a id="wildcards"/>
 
@@ -143,7 +143,7 @@ The capabilities for tokens are determined based on those of the issuing API key
 
 #### 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/authentication#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.
 
@@ -257,7 +257,7 @@ 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/authentication#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
@@ -413,7 +413,7 @@ 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/authentication#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
@@ -507,7 +507,7 @@ final tokenDetails = await realtime.auth.requestToken(tokenParams: tokenParams);
 
 #### 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/authentication#json-web-tokens-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.