From a01203bd84d721473099f463f37c369f355c826a Mon Sep 17 00:00:00 2001 From: ginatkins Date: Fri, 19 Jun 2026 19:57:41 +1000 Subject: [PATCH 1/5] Document agent service accounts and agent API keys Adds docs for the new Agent Service Account identity type and agent API key support introduced in the Agent Governance project, including how to create them, the API Keys page management UX (type tags, AI agent filter, last-used timestamp, view permissions shortcut), and cross-links between the two pages. Co-Authored-By: Claude Sonnet 4.6 --- .../how-to-create-an-api-key.md | 35 ++++++++++++++++++- .../users-and-teams/service-accounts.md | 16 ++++++++- 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/octopus-rest-api/how-to-create-an-api-key.md b/src/pages/docs/octopus-rest-api/how-to-create-an-api-key.md index 7bd48628c3..83313740dd 100644 --- a/src/pages/docs/octopus-rest-api/how-to-create-an-api-key.md +++ b/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-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} diff --git a/src/pages/docs/security/users-and-teams/service-accounts.md b/src/pages/docs/security/users-and-teams/service-accounts.md index 7a15c67b60..92afb1b05f 100644 --- a/src/pages/docs/security/users-and-teams/service-accounts.md +++ b/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. From a8c6cb4defca7b12e428fac3fab216ce9f1a69ca Mon Sep 17 00:00:00 2001 From: ginatkins Date: Fri, 19 Jun 2026 20:01:56 +1000 Subject: [PATCH 2/5] Document agent activity filtering and attribution in audit log Adds a note that agent API key names are captured in audit events for attribution, and documents the AI Agents filter for narrowing the audit log to agent activity only. Co-Authored-By: Claude Sonnet 4.6 --- src/pages/docs/security/users-and-teams/auditing/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/pages/docs/security/users-and-teams/auditing/index.md b/src/pages/docs/security/users-and-teams/auditing/index.md index b9b5876772..5f4a440423 100644 --- a/src/pages/docs/security/users-and-teams/auditing/index.md +++ b/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,6 +22,7 @@ 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 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). @@ -29,6 +30,8 @@ If you are concerned that Octopus does not capture a specific action of interest 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) ::: From 696cb1cc3fdb7152baf8a7f619bc0307ea1c6444 Mon Sep 17 00:00:00 2001 From: ginatkins Date: Fri, 19 Jun 2026 20:08:37 +1000 Subject: [PATCH 3/5] Clarify wording on agent activity attribution in audit log Co-Authored-By: Claude Sonnet 4.6 --- src/pages/docs/security/users-and-teams/auditing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/security/users-and-teams/auditing/index.md b/src/pages/docs/security/users-and-teams/auditing/index.md index 5f4a440423..47423d798b 100644 --- a/src/pages/docs/security/users-and-teams/auditing/index.md +++ b/src/pages/docs/security/users-and-teams/auditing/index.md @@ -22,7 +22,7 @@ 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 activity back to a specific credential and its owner. +- 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). From 59bfef61b6079ab348b965f2952c100373f2ebe1 Mon Sep 17 00:00:00 2001 From: ginatkins Date: Fri, 19 Jun 2026 20:13:16 +1000 Subject: [PATCH 4/5] Recommend agent service account and agent API key for MCP setup Updates the MCP server requirements to recommend creating a dedicated Agent Service Account and agent API key rather than a generic API key, with links to the relevant docs and a brief explanation of the benefits. Co-Authored-By: Claude Sonnet 4.6 --- src/pages/docs/octopus-ai/mcp/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/octopus-ai/mcp/index.mdx b/src/pages/docs/octopus-ai/mcp/index.mdx index 9c34c3dc6b..5ed1d1d2c1 100644 --- a/src/pages/docs/octopus-ai/mcp/index.mdx +++ b/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 From e78ea1833045627db1a5efa8c65d64dc9d778fea Mon Sep 17 00:00:00 2001 From: Steve Fenton <99181436+steve-fenton-octopus@users.noreply.github.com> Date: Wed, 24 Jun 2026 09:43:29 +0100 Subject: [PATCH 5/5] Clarify behavior of trusted proxies and IP addresses --- src/pages/docs/security/users-and-teams/auditing/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/docs/security/users-and-teams/auditing/index.md b/src/pages/docs/security/users-and-teams/auditing/index.md index 47423d798b..570ee52951 100644 --- a/src/pages/docs/security/users-and-teams/auditing/index.md +++ b/src/pages/docs/security/users-and-teams/auditing/index.md @@ -106,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