Merge pull request #3219 from ginatkins/agent-governance-stream-1-docs

Agent governance docs — service accounts, API keys, audit log, MCP setupAgent governance stream 1 docs

Author: ginatkins

src/pages/docs/octopus-ai/mcp/index.mdx

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-04-04
-modDate: 2025-08-01
+modDate: 2026-06-19
 title: Octopus MCP
 navTitle: Overview
 navSection: Octopus MCP
@@ -36,7 +36,7 @@ To learn more, read our [Octopus REST API](/docs/octopus-rest-api) documentation
 
 - Node.js >= v20.0.0
 - Octopus Deploy instance that can be accessed by the MCP server via HTTPS
-- Octopus Deploy API Key
+- Octopus Deploy API key (we recommend creating a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and generating an [agent API key](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) under it — this gives the MCP server its own identity, scopes its permissions, and makes its activity identifiable in the audit log and on the API Keys page)
 
 ### Configuration
 

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: 2026-06-18
+modDate: 2026-06-19
 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
@@ -29,6 +29,19 @@ You can create API keys by performing the following steps:
 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).
 :::
 
+## Creating an agent API key {#creating-an-agent-api-key}
+
+If you're connecting an AI agent to Octopus—such as the [Octopus MCP server](/docs/octopus-ai/mcp)—create a dedicated agent API key rather than a regular one. Agent keys are tagged throughout Octopus so you can filter for and audit agent activity separately from human activity.
+
+The recommended approach is to first create an [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) for your agent. Any API key created under an agent service account is automatically tagged as an agent key.
+
+You can also create an agent API key directly from the **Manage API Keys** page:
+
+1. Click **New Agent Key** and state the purpose of the key.
+1. Choose the level of **Access** to grant.
+1. Click **Generate new**.
+1. Copy the new API key to your clipboard.
+
 ## Choosing an access level
 
 :::div{.hint}
@@ -97,6 +110,26 @@ To change these values in the Octopus Web Portal:
 1. Expand the sections for **API Key default expiry (days)** and **API Key maximum expiry (days)** and alter the values.
 1. Click Save.
 
+## Managing API keys
+
+Octopus administrators can view all API keys across the instance from the **API Keys** page.
+
+### Identifying key types
+
+Each key's row shows an **API key type** column with a type tag—**User**, or **AI Agent**—so you can tell at a glance which kind of identity each key belongs to.
+
+### Filtering by agent
+
+Check **AI Agents** to filter the list to agent keys only. This is useful when you want to review the credentials your agents are using without wading through keys belonging to human users.
+
+### Last used
+
+The list shows when each key was last used. Use this to spot dormant credentials that may need rotating.
+
+### Viewing permissions
+
+Each row has an overflow menu. Select **View permissions** to open the Test Permissions page for that identity, so you can see exactly what the key can do.
+
 ## Disabling API key creation for user accounts
 
 :::div{.hint}

src/pages/docs/security/users-and-teams/auditing/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2026-06-19
 title: Auditing
 description: Octopus Deploy captures audit information whenever significant events happen in the system.
 ---
@@ -22,13 +22,16 @@ Some general points worth noting:
 - Octopus **does** capture the details of every mutating action (create/edit/delete) including who initiated the action.
 - Octopus **does** capture login events for specific user accounts, but **not** logout.
 - Octopus **does not** capture when data is read, however certain sensitive actions like downloading a certificate with its private key is captured.
+- When an action is performed via an [agent API key](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key), Octopus captures the API key name alongside the action, so you can trace agent activity back to a specific credential and its owner.
 
 If you are concerned that Octopus does not capture a specific action of interest to you, please contact our [support team](https://octopus.com/support).
 
 ## Viewing the audit history
 
 You can view the full audit history by navigating to the **Audit** tab in the **Configuration** area.
 
+To filter the log to actions taken by AI agents only, check **AI Agents** in the filter options. This lets you review agent activity without wading through actions taken by human users.
+
 :::figure
 ![Audit Configuration](/docs/img/security/users-and-teams/auditing/images/audit-configuration.png)
 :::
@@ -103,6 +106,7 @@ From **Octopus 2023.1**, the originating IP address of a request is recorded as
 Octopus accepts any number of trusted proxies. A trusted proxy can either be a single IP address such as `192.168.123.111` or an IP range such as `192.168.0.0/16`.
 
 Octopus reads forwarded IP addresses from the `X-Forwarded-For` header. Given the IP address of the client sending the request is trusted, the rightmost IP address that is **not** configured in the list of trusted proxies will be used as the IP address for the event. If all IP addresses are trusted, the leftmost value in the `X-Forwarded-For` header will be used. Some examples include:
+
 - If the IP range `0.0.0.0/0` is configured as a trusted proxy, then any request will always use the leftmost IP address found in the `X-Forwarded-For` header, or the IP address of the client if no header is provided
 - If no trusted proxies are configured, the IP address of the client that sent the request will always be used as it is not considered trusted, even if there is a valid `X-Forwarded-For` header
 - If the IP address `192.168.123.111` is configured as a trusted proxy, and a request is received with a client IP address of `192.168.123.111` and the header `X-Forwarded-For: 100.100.101.102, 200.123.124.125`, then `200.123.124.125` will be used as the IP address of this request as it is the rightmost untrusted IP address

src/pages/docs/security/users-and-teams/service-accounts.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-10-27
+modDate: 2026-06-19
 title: Service accounts
 description: Creating Service Accounts to provide individual services with the least privileges required for the tasks they will perform.
 navOrder: 2
@@ -52,6 +52,20 @@ You can use [OpenID Connect (OIDC)](/docs/octopus-rest-api/openid-connect) to au
 
 Once you have created an [Octopus API key](/docs/octopus-rest-api/how-to-create-an-api-key/) and [added this Service account to a team](/docs/security/users-and-teams), you can start using this Service account to automate Octopus with another service.
 
+## Agent service accounts {#agent-service-accounts}
+
+If you're connecting an AI agent to Octopus—such as the [Octopus MCP server](/docs/octopus-ai/mcp) or any other automated tooling that runs without a human user session—create an **Agent Service Account** rather than a regular service account. Agent service accounts are a dedicated identity type for AI agents, and they're labeled as such across the product, making agent activity easy to identify and audit.
+
+Any API key created under an agent service account is automatically treated as an agent key. This means you can filter for agent activity separately from human activity in the [audit log](/docs/security/users-and-teams/auditing) and on the **API Keys** page.
+
+To create an agent service account:
+
+1. Go to **Configuration ➜ Users** and click **Add AI service account**.
+2. Enter a **Service Username** and **Service Display Name** for the agent.
+3. Save the user.
+
+Once created, [add the agent service account to one or more teams](/docs/security/users-and-teams) to grant it the permissions it needs, then [create an agent API key](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) for it.
+
 ## Logins
 
 If you are using Active Directory there is also the option of using an Active Directory account's group membership to determine the service account's Team membership. To use this option all you need to do is add the Active Directory account as an external login entry for the service account.