From 7830ef71d5588213b15fa9c28925e42ba87f1db1 Mon Sep 17 00:00:00 2001
From: matt423 <matthew.a423@gmail.com>
Date: Wed, 25 Mar 2026 13:33:11 +0000
Subject: [PATCH 1/2] Document access token expiration and rotation

Add token expiration and rotation sections to the access tokens page,
covering expiry options, reminder emails, and the rotation workflow.
---
 .../docs/platform/account/access-tokens.mdx   | 44 +++++++++++++++++--
 1 file changed, 40 insertions(+), 4 deletions(-)

diff --git a/src/pages/docs/platform/account/access-tokens.mdx b/src/pages/docs/platform/account/access-tokens.mdx
index bee485dba9..6d0a990cb8 100644
--- a/src/pages/docs/platform/account/access-tokens.mdx
+++ b/src/pages/docs/platform/account/access-tokens.mdx
@@ -1,7 +1,7 @@
 ---
 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"
+meta_description: "Create and manage access tokens to authenticate with the Ably Control API and Ably CLI, including expiration and rotation."
+meta_keywords: "access tokens, Control API, Ably CLI, authentication, capabilities, token expiration, token rotation"
 ---
 
 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.
@@ -16,8 +16,9 @@ To create a new access token:
 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**.
+5. Select an **Expiry** period for the token. Choose from 30 days, 60 days, 90 days, or no expiry. The default is 30 days.
+6. 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.
+7. Click **Create token**.
 
 <Aside data-type='important'>
 Copy your access token immediately after creation. The full token is only displayed once and cannot be retrieved later. Only the token ID is visible after you navigate away.
@@ -41,6 +42,41 @@ Capabilities control which operations the token can perform in the Control API a
 | 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` |
 
+## Token expiration <a id="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 expiry
+
+The default expiry is 30 days. Ably recommends setting an expiry period so that tokens are rotated periodically. Selecting "No expiry" means the token remains valid indefinitely unless revoked. The expiration date is visible in the token list on the [Access tokens](https://ably.com/users/access_tokens) page.
+<Aside data-type='note'>
+Ably sends reminder emails 7 days and 1 day before a token expires. Use these reminders to rotate or replace tokens before they expire.
+</Aside>
+
+## Rotate an access token <a id="rotate"/>
+
+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:
+
+1. Go to the [Access tokens](https://ably.com/users/access_tokens) page in the Ably dashboard.
+2. Click the rotate icon next to the token you want to rotate.
+3. Select a new **Expiry** period for the rotated token.
+4. 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.
+
+<Aside data-type='important'>
+Copy the new token value immediately after rotation. As with token creation, the full token is only displayed once and cannot be retrieved later.
+</Aside>
+
 ## Revoke an access token <a id="revoke"/>
 
 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.

From c179b113440d7fd6f6f9f1f09405ab38d6b4ad87 Mon Sep 17 00:00:00 2001
From: matt423 <matthew.a423@gmail.com>
Date: Thu, 26 Mar 2026 15:22:37 +0000
Subject: [PATCH 2/2] Add expires_at to Control API token schema and /me
 response example

---
 src/pages/docs/platform/account/control-api.mdx | 5 +++--
 static/open-specs/control-v1.yaml               | 7 +++++++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/pages/docs/platform/account/control-api.mdx b/src/pages/docs/platform/account/control-api.mdx
index 64afccc47d..caf75c0c8f 100644
--- a/src/pages/docs/platform/account/control-api.mdx
+++ b/src/pages/docs/platform/account/control-api.mdx
@@ -54,7 +54,7 @@ curl -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' ...
 
 ### Obtain token details using the Control API <a id="obtain-token"/>
 
-You can use the Control API to obtain information about your access token, such as its capabilities and the user and account it is assigned to. This is shown in the following request:
+You can use the Control API to obtain information about your access token, such as its capabilities, expiration date, and the user and account it is assigned to. This is shown in the following request:
 
 <Code>
 ```shell
@@ -82,7 +82,8 @@ Sample response:
             "read:key",
             "write:app",
             "read:app"
-        ]
+        ],
+        "expires_at": "2026-04-25T00:00:00Z"
     },
     "user": {
         "id": 12140,
diff --git a/static/open-specs/control-v1.yaml b/static/open-specs/control-v1.yaml
index 2cb36dacf7..7db28823a5 100644
--- a/static/open-specs/control-v1.yaml
+++ b/static/open-specs/control-v1.yaml
@@ -5284,10 +5284,17 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz
               example: ["write:namespace", "read:namespace", "write:queue", "read:queue", "write:rule", "read:rule", "write:key", "read:key", "write:app", "read:app"]
               items:
                 type: string
+            expires_at:
+              type: string
+              format: date-time
+              nullable: true
+              description: The date and time at which the access token expires, in ISO 8601 format. A value of `null` indicates the token does not expire.
+              example: "2026-04-25T00:00:00Z"
           required:
           - id
           - name
           - capabilities
+          - expires_at
         user:
           type: object
           additionalProperties: false