Document scoped (read-only) API key access levels

src/pages/docs/octopus-rest-api/how-to-create-an-api-key.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2025-05-12
+modDate: 2025-06-18
 title: How to Create an API Key
 description: How to create an API key to interact with Octopus without the need for a username and password.
 navOrder: 10
@@ -19,14 +19,32 @@ You can create API keys by performing the following steps:
 
 1. Log into the Octopus Web Portal, click your profile image and select **Profile**.
 1. Click **My API Keys**.
-1. Click **New API key**, state the purpose of the API key and click **Generate new**.
+1. Click **New API key**, state the purpose of the API key.
+1. Choose the level of **Access** to grant (see below).
+1. Click **Generate new**.
 1. Copy the new API key to your clipboard.
 
 :::div{.warning}
 **Write Your Key Down**
 After you generate an API key, it cannot be retrieved from the Octopus Web Portal again, we store only a one-way hash of the API key. If you want to use the API key again, you need to store it in a secure place such as a password manager. Read about [why we hash API keys](https://octopus.com/blog/hashing-api-keys).
 :::
 
+## Choosing an access level
+
+:::div{.hint}
+
+This feature is currently being rolled out to Octopus Cloud customers and will become available to self-hosted installations in Octopus Server 2026.3.
+
+If you don't see the access option when creating an API key, the API key will be created with full access and have the same permissions as your user account.
+
+:::
+
+Recent versions of Octopus Server add the ability to limit the scope of an API key, to allow only read-only access. Alternatively, you can grant the API key full access to give it the same permissions as your user account. Use the **Preview Permissions** link to see the exact list of permissions that apply to the chosen access level.
+
+Read-only scopes are useful for tooling that doesn't need to be able to make changes, perform actions or trigger deployments, such as AI agents (like Claude Code) or for external monitoring systems (like release progression dashboards).
+
+Note that it is not possible to create an API key with more permissions than your user account. For these scenarios, you should look at creating an API key under a dedicated [Service Account](/docs/security/users-and-teams/service-accounts) instead. Use this approach for tooling that is not acting on behalf of a particular user.
+
 ## Setting an expiry date
 
 :::div{.hint}
@@ -58,7 +76,8 @@ The background task which raises the api-key-expiry events runs:
 
 - 10 minutes after the Octopus Server service starts
 - Every 4 hours
-  :::
+
+:::
 
 ## Configuring API Key default and maximum expiry durations
 
@@ -90,4 +109,4 @@ To change the value in the Octopus Web Portal:
 
 1. Navigate to **Configuration ➜ Settings** and click **Authentication**.
 1. Expand the section for **User API Keys** and alter the value.
-1. Click Save.
+1. Click Save.