Access tokens authenticate requests to the Control API and the Ably CLI. They are scoped to a specific account and grant a configurable set of capabilities. Manage your tokens from the 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:
- Go to the Access tokens page in the Ably dashboard.
- Click Create new token.
- Enter a Name for the token. This is for your reference only and is not used in API requests.
- Select the Account the token is scoped to. This is auto-selected if you only have one account.
- Select an Expiry period for the token. Choose from 30 days, 60 days, 90 days, or no expiration. The default is 30 days.
- 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.
- 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 apps | ably apps list |
| Write App | write:app | Create, update, and delete apps | ably apps create, ably apps update, ably apps delete |
| Read Key | read:key | List API keys for an app | ably auth keys list, ably auth keys get |
| Write Key | write:key | Create, update, and revoke API keys | ably auth keys create, ably auth keys update, ably auth keys revoke |
| Read Integration | read:rule | List and get integration rules | ably integrations list, ably integrations get |
| Write Integration | write:rule | Create, update, and delete integration rules | ably integrations create, ably integrations update, ably integrations delete |
| Read Queue | read:queue | List queues for an app | ably queues list |
| Write Queue | write:queue | Create and delete queues | ably queues create, ably queues delete |
| Read Rule | read:namespace | List rules for an app | ably apps channel-rules list |
| Write Rule | write:namespace | Create, update, and delete rules | ably apps channel-rules create, ably apps channel-rules update, ably apps channel-rules delete |
| Read Stats | read:stats | Account and app statistics | ably stats account, ably stats app |
Token expiration
Access tokens can have an expiration date. When a token expires, any request that uses it receives a 401 Unauthorized response from the Control API, and the token can no longer authenticate CLI commands.
The expiry period is set when you create a token. The available options are:
- 30 days
- 60 days
- 90 days
- No expiration
The default expiry is 30 days. Ably recommends setting an expiry period so that tokens are rotated periodically. Selecting "No expiration" means the token remains valid indefinitely unless revoked. The expiration date is visible in the token list on the Access tokens page.
Rotate an access token
Rotating an access token regenerates its value while preserving the token name, capabilities, and account association. Use rotation to replace a token that is approaching expiration or if the token value may have been exposed.
You must be an account admin to rotate access tokens.
To rotate a token:
- Go to the Access tokens page in the Ably dashboard.
- Click the rotate icon next to the token you want to rotate.
- Select a new Expiry period for the rotated token.
- Click Confirm to complete the rotation.
The previous token value is invalidated immediately. Any systems using the old value must be updated with the new token.
Revoke an access token
Revoke an access token from the 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 for details.