diff --git a/src/data/nav/platform.ts b/src/data/nav/platform.ts index 8e1df1417d..38a8b53a47 100644 --- a/src/data/nav/platform.ts +++ b/src/data/nav/platform.ts @@ -325,6 +325,10 @@ export default { }, ], }, + { + name: 'Access tokens', + link: '/docs/platform/account/access-tokens', + }, { name: 'Programmatic management using Control API', link: '/docs/platform/account/control-api', diff --git a/src/pages/docs/platform/account/access-tokens.mdx b/src/pages/docs/platform/account/access-tokens.mdx new file mode 100644 index 0000000000..bee485dba9 --- /dev/null +++ b/src/pages/docs/platform/account/access-tokens.mdx @@ -0,0 +1,50 @@ +--- +title: "Access tokens" +meta_description: "Create and manage access tokens to authenticate with the Ably Control API and Ably CLI." +meta_keywords: "access tokens, Control API, Ably CLI, authentication, capabilities" +--- + +Access tokens authenticate requests to the [Control API](/docs/platform/account/control-api) and the [Ably CLI](/docs/platform/tools/cli). They are scoped to a specific account and grant a configurable set of capabilities. Manage your tokens from the [Access tokens](https://ably.com/users/access_tokens) page in the Ably dashboard. + +## Create an access token + +You must be an account admin to create access tokens. If you don't see the "Create new token" button, contact your account administrator. + +To create a new access token: + +1. Go to the [Access tokens](https://ably.com/users/access_tokens) page in the Ably dashboard. +2. Click **Create new token**. +3. Enter a **Name** for the token. This is for your reference only and is not used in API requests. +4. Select the **Account** the token is scoped to. This is auto-selected if you only have one account. +5. Select the **Capabilities** the token requires. Capabilities are grouped into categories such as Apps, Keys, Rules, Queues, Namespaces, and Statistics. Each category has individual read and write checkboxes, and a "Select all" toggle. +6. Click **Create token**. + + + +## Access token capabilities + +Capabilities control which operations the token can perform in the Control API and CLI. The dashboard displays human-readable labels such as "Read App". The raw format such as `read:app` appears in API responses and JWTs. + +| Dashboard label | API capability | Control API | CLI commands | +| --- | --- | --- | --- | +| Read App | `read:app` | [List](/docs/api/control-api#tag/apps/paths/~1accounts~1{account_id}~1apps/get) apps | `ably apps list` | +| Write App | `write:app` | [Create](/docs/api/control-api#tag/apps/paths/~1accounts~1{account_id}~1apps/post), [update](/docs/api/control-api#tag/apps/paths/~1apps~1{id}/patch), and [delete](/docs/api/control-api#tag/apps/paths/~1apps~1{id}/delete) apps | `ably apps create`, `ably apps update`, `ably apps delete` | +| Read Key | `read:key` | [List](/docs/api/control-api#tag/keys/paths/~1apps~1{app_id}~1keys/get) API keys for an app | `ably auth keys list`, `ably auth keys get` | +| Write Key | `write:key` | [Create](/docs/api/control-api#tag/keys/paths/~1apps~1{app_id}~1keys/post), [update](/docs/api/control-api#tag/keys/paths/~1apps~1{app_id}~1keys~1{key_id}/patch), and [revoke](/docs/api/control-api#tag/keys/paths/~1apps~1{app_id}~1keys~1{key_id}~1revoke/post) API keys | `ably auth keys create`, `ably auth keys update`, `ably auth keys revoke` | +| Read Integration | `read:rule` | [List](/docs/api/control-api#tag/rules/paths/~1apps~1{app_id}~1rules/get) and [get](/docs/api/control-api#tag/rules/paths/~1apps~1{app_id}~1rules~1{rule_id}/get) integration rules | `ably integrations list`, `ably integrations get` | +| Write Integration | `write:rule` | [Create](/docs/api/control-api#tag/rules/paths/~1apps~1{app_id}~1rules/post), [update](/docs/api/control-api#tag/rules/paths/~1apps~1{app_id}~1rules~1{rule_id}/patch), and [delete](/docs/api/control-api#tag/rules/paths/~1apps~1{app_id}~1rules~1{rule_id}/delete) integration rules | `ably integrations create`, `ably integrations update`, `ably integrations delete` | +| Read Queue | `read:queue` | [List](/docs/api/control-api#tag/queues/paths/~1apps~1{app_id}~1queues/get) queues for an app | `ably queues list` | +| Write Queue | `write:queue` | [Create](/docs/api/control-api#tag/queues/paths/~1apps~1{app_id}~1queues/post) and [delete](/docs/api/control-api#tag/queues/paths/~1apps~1{app_id}~1queues~1{queue_id}/delete) queues | `ably queues create`, `ably queues delete` | +| Read Rule | `read:namespace` | [List](/docs/api/control-api#tag/namespaces/paths/~1apps~1{app_id}~1namespaces/get) rules for an app | `ably apps channel-rules list` | +| Write Rule | `write:namespace` | [Create](/docs/api/control-api#tag/namespaces/paths/~1apps~1{app_id}~1namespaces/post), [update](/docs/api/control-api#tag/namespaces/paths/~1apps~1{app_id}~1namespaces~1{namespace_id}/patch), and [delete](/docs/api/control-api#tag/namespaces/paths/~1apps~1{app_id}~1namespaces~1{namespace_id}/delete) rules | `ably apps channel-rules create`, `ably apps channel-rules update`, `ably apps channel-rules delete` | +| Read Stats | `read:stats` | [Account](/docs/api/control-api#tag/accounts/paths/~1accounts~1{id}~1stats/get) and [app](/docs/api/control-api#tag/apps/paths/~1apps~1{id}~1stats/get) statistics | `ably stats account`, `ably stats app` | + +## Revoke an access token + +Revoke an access token from the [Access tokens](https://ably.com/users/access_tokens) page by clicking the delete icon next to the token. Revocation is immediate and irreversible. Any requests using that token will fail. + +## Rate limits + +The Control API limits the number of requests per account and per access token per hour. See [API limits](/docs/platform/pricing/limits#api) for details. diff --git a/src/pages/docs/platform/account/control-api.mdx b/src/pages/docs/platform/account/control-api.mdx index 8f7ceb42a6..64afccc47d 100644 --- a/src/pages/docs/platform/account/control-api.mdx +++ b/src/pages/docs/platform/account/control-api.mdx @@ -30,9 +30,9 @@ The following diagram illustrates an example use case: In this use case, Control API is used to provision a sample app for review and testing purposes. Once provisioned, the [realtime](/docs/api/realtime-sdk) or [REST API](/docs/api/rest-api) can be used to test the app as needed. Once fully tested, the Control API can be used to replicate the app for users as required, using the known-good configuration. -In order to use the Control API you must first create an access token in the [Ably dashboard](https://ably.com/accounts/any). You can then use the Control API to manage many account functions without having to interact with the dashboard. +In order to use the Control API you must first [create an access token](/docs/platform/account/access-tokens). You can then use the Control API to manage many account functions without having to interact with the dashboard. -Note that the Control API has certain [limits](/docs/platform/pricing/limits#api) on the number of API calls that can be made per hour. +The Control API limits the number of requests per account and per access token per hour. See [API limits](/docs/platform/pricing/limits#api) for details. ## OpenAPI document @@ -44,31 +44,7 @@ Using the code-generation capabilities of tools such as [Postman](https://www.po ## Authentication -Before you can use the Control API you must create an access token to authenticate with. You can do this in the Ably dashboard. - -In the [Ably dashboard](https://ably.com/accounts/any), on the top menu bar, select your account from the dropdown list and then select **My Access Tokens** from the menu: - -![My Settings](../../../../images/content/screenshots/control-api/my-access-tokens-menu-item.png) - -You are presented with the **My Access Tokens** area, where you can create tokens for use with the Control API: - -![My Settings](../../../../images/content/screenshots/control-api/my-access-tokens.png) - -### Creating an access token - -To create a new token, click the **Create new access token** button. Then enter the required information into the dialog: - -1. Enter a memorable name for your token. -2. Select the capabilities you wish the token to have, depending on your use case. -3. Click the **Create** button to create the token. - -![My Settings](../../../../images/content/screenshots/control-api/new-access-token.png) - -### Using the access token - -From the **My access tokens** area you can click the **Copy Token** button, to copy the token to the clipboard. - -You use the access token to authenticate requests to the Control API. To do this, you supply the access token as a Bearer token in the Authorization header of the HTTP request. For example, in the following Curl request replace `` with the token you have copied to the clipboard: +To use the Control API you must first [create an access token](/docs/platform/account/access-tokens). You use the access token to authenticate requests by supplying it as a Bearer token in the Authorization header of the HTTP request. For example, in the following curl request replace `` with your token: ```shell @@ -835,7 +811,7 @@ You have now imported the OpenAPI document into Postman. ### Sending a request -First, you need to [obtain a Control API token](#creating-access-token) to authenticate any requests you send to the Control API. +First, you need to [obtain a Control API token](/docs/platform/account/access-tokens#create) to authenticate any requests you send to the Control API. For many Control API requests you also need to specify your account ID or app ID. You can see the [account ID and app ID](#ids) section for details on how to obtain these. diff --git a/src/pages/docs/platform/account/index.mdx b/src/pages/docs/platform/account/index.mdx index 98b7715222..56cb255665 100644 --- a/src/pages/docs/platform/account/index.mdx +++ b/src/pages/docs/platform/account/index.mdx @@ -62,10 +62,10 @@ Control personal account settings: * Customize Ably email preferences (product updates, news, educational emails) * Set up notifications for account usage. -### My Access tokens +### Access tokens -Create access tokens for the [Control API:](/docs/platform/account/control-api) +Create and manage [access tokens](/docs/platform/account/access-tokens) for the Control API and the Ably CLI: -* Users can create new tokens by providing a descriptive name, assigning an account, selecting capabilities, and securely storing the token once generated. -* Users can revoke existing tokens through the settings section, but this action is irreversible and will immediately invalidate the token for API access. -* After a token is created, the full token cannot be viewed again, so it must be securely stored upon generation. +* Create new tokens by providing a descriptive name, assigning an account, and selecting capabilities. +* Copy the token immediately after creation. The full token is only displayed once. +* Revoke existing tokens from the Access tokens page. Revocation is immediate and irreversible. diff --git a/src/pages/docs/platform/tools/cli.mdx b/src/pages/docs/platform/tools/cli.mdx index fcd61f7dda..e0c02644ef 100644 --- a/src/pages/docs/platform/tools/cli.mdx +++ b/src/pages/docs/platform/tools/cli.mdx @@ -31,7 +31,7 @@ npm install -g @ably/cli ``` -2. Run the following to log in to your Ably account. This will prompt you to log into your Ably account and setup an access token for the Ably CLI. You can then set the default app and API key to use back in your terminal instance: +2. Run the following to log in to your Ably account. This will prompt you to log into your Ably account and set up an [access token](/docs/platform/account/access-tokens) for the Ably CLI. You can then set the default app and API key to use back in your terminal instance: ```shell