docs: cover Personal / Team / Agent API key types

src/content/docs/agent-platform/cloud-agents/agents.mdx

@@ -8,23 +8,64 @@ sidebar:
   label: "Agent identities"
 ---
 
-An **agent identity** is a team-scoped identity that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity. Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person.
+An **agent identity** is a team-scoped bot account that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity (`Default Service Account`). Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot rather than to a person.
+
+Think of an agent identity like an IAM service account: it has a name, a description, its own set of managed secrets, and its own preloaded skills. When you bind an [API key](/reference/cli/api-keys/) to it, every automated run authenticated by that key executes *as* that bot — with that bot's credentials, that bot's skills, and that bot's name in the dashboard.
 
 Agent identities are useful when you want to:
 
-* **Separate workflows** - Give the deploy bot, the dependency-update bot, and the code-review bot distinct identities so runs are easier to filter and audit.
-* **Scope credentials** - Attach a specific set of managed secrets and skills to one identity so its runs receive only the configuration that workflow needs.
-* **Attribute automated work** - Bind an API key to an agent identity so CI pipelines and webhooks show up as that bot in run history rather than as a teammate.
+* **Separate workflows** — Give the deploy bot, the dependency-update bot, and the PR-review bot distinct identities. A `deploy-bot` for production deploys, a `dependabot-runner` for nightly upgrades, a `pr-reviewer` for inline code review. Runs are filterable by identity in the [Oz dashboard](https://oz.warp.dev/runs), and individual run pages show which bot ran the task.
+* **Scope credentials** — Attach managed secrets to one identity so its runs receive only the configuration that workflow needs. A `deploy-bot` identity can hold `DEPLOY_TOKEN` and `DATABASE_URL` for production deploys; a `pr-reviewer` identity holds neither, because its runs never need to deploy.
+* **Preload skills** — Attach [skill specs](/agent-platform/capabilities/skills/) to an identity so every run starts with the right instructions. A `pr-reviewer` identity preloaded with `org/repo:.warp/skills/code-review/SKILL.md` doesn't need a `--skill` flag at every invocation.
+* **Attribute automated work** — CI pipelines, webhooks, and scheduled jobs that authenticate with an agent identity's API key show up in run history as that bot, not as a teammate. Audit trails stay attributable to the workflow, not the person who happened to set up the key.
 
 ## How agent identities work
 
-Each team has one default agent identity. Headless runs (such as team API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities.
+Each team has one default agent identity, called `Default Service Account`. Automated runs (such as agent API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities.
 
 You can attach the following configuration to an agent identity:
 
-* **Description** - A short, human-readable summary teammates see when picking the identity.
-* **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to.
-* **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments.
+* **Description** — A short, human-readable summary teammates see when picking the identity.
+* **Managed secrets** — References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to.
+* **Skills** — Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments.
+
+## Quickstart: create a custom agent identity
+
+This walkthrough creates a `deploy-bot` identity, gives it a deploy secret and a deploy skill, generates an API key bound to it, and uses that key to trigger a run that shows up in the dashboard attributed to `deploy-bot`.
+
+1. **Create a managed secret** the identity will need (skip if your team already has one). In the [Oz web app](https://oz.warp.dev/secrets), add a `DEPLOY_TOKEN` team-scoped secret. See [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) for the full secret-management flow.
+2. **Create the agent identity.** Send a `POST` to `/api/v1/agent/identities` with your existing API key (or use the Agents page at [oz.warp.dev/agents](https://oz.warp.dev/agents) once it's wired up to a UI):
+
+   ```bash
+   curl -X POST https://app.warp.dev/api/v1/agent/identities \
+     -H "Authorization: Bearer $WARP_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "name": "deploy-bot",
+       "description": "Handles production deploys off main.",
+       "secrets": [{"name": "DEPLOY_TOKEN"}],
+       "skills": ["warpdotdev/warp-server:.claude/skills/deploy/SKILL.md"]
+     }'
+   ```
+
+   **Expected outcome:** A `201 Created` response with the new identity's `uid`, `name`, and `available: true`.
+3. **Generate an API key bound to the identity.** In [oz.warp.dev/settings](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, select `deploy-bot` from the dropdown, name the key, and copy the raw value. See [API keys](/reference/cli/api-keys/) for the full creation flow.
+4. **Use the key to run an agent.** Export the key and trigger a run — the agent will have `DEPLOY_TOKEN` injected automatically and the `deploy` skill preloaded:
+
+   ```bash
+   export WARP_API_KEY="wk-..."
+   oz agent run-cloud --environment <ENV_ID> --prompt "Deploy the latest main to production"
+   ```
+
+5. **Confirm attribution.** Open the [Oz dashboard](https://oz.warp.dev/runs) and filter by agent identity. The run shows up under `deploy-bot`, not under your user account.
+
+The same pattern works for any per-workflow identity: a `pr-reviewer` identity with read-only GitHub access and a code-review skill, a `nightly-jobs` identity used by scheduled cleanups, an `on-call` identity that holds incident-playbook skills and production credentials.
+
+## Agent API keys
+
+An **agent API key** is the credential that lets an automated caller (CI, scheduler, webhook handler) execute as a specific agent identity. The key is bound to one identity at creation time and inherits that identity's secrets and skills for every run.
+
+See [API keys](/reference/cli/api-keys/) for the full creation flow, the per-surface (Oz web app vs. Warp desktop app) differences, and the relationship to legacy "team API keys."
 
 ## Service accounts and agent identities
 
@@ -66,22 +107,14 @@ A few constraints apply across every endpoint:
 * **Human callers only** - Only human users can create, update, or delete an agent identity. A request authenticated as an agent identity itself is rejected.
 * **Availability is enforced on use** - Over-plan-limit identities are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs.
 
-## API keys bound to an agent identity
-
-A team API key can be bound to a specific agent identity at creation time. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key.
-
-To create a key bound to an agent identity, choose the identity when creating the team API key. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys.
-
-Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself.
-
 ## Running as an agent identity
 
 There are two ways to run a cloud agent as a specific agent identity:
 
 * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work.
 * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs.
 
-When neither path is used, headless runs (team API key runs without an identity) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app.
+When neither path is used, automated runs (agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app.
 
 ## Where agent identities appear in the product
 

src/content/docs/agent-platform/cloud-agents/environments.mdx

@@ -133,7 +133,7 @@ You can create and configure environments with Warp’s guided setup, or through
 Make sure you have:
 
 * One or more GitHub repositories that the agent should clone and work in.
-* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using team API keys, configure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel.
+* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using an agent API key, configure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel.
 * A publicly-accessible Docker image that can build and run your code. Official images like [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), or [rust](https://hub.docker.com/_/rust) work for many projects. You can also use one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments).
 
 :::caution

src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx

@@ -41,7 +41,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and:
 
 To use agents in GitHub Actions, you need:
 
-* A [**Warp API Key**](/reference/cli/#generating-api-keys) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp
+* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an [agent key](/agent-platform/cloud-agents/agents/) for automated runs (no specific user behind them). See [API keys](/reference/cli/api-keys/) for when to pick each.
 * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow
 * The `oz-agent-action` step added to your workflow
 * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details)

src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx

@@ -13,7 +13,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git
 
 ## Prerequisites
 
-* **Warp API key** - In the Warp app, click your profile photo, then go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create one. Use a personal key if the agent needs to write to your repo. See [API Keys](/reference/cli/api-keys/) for details.
+* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key bound to an [agent identity](/agent-platform/cloud-agents/agents/) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for automated runs. See [API Keys](/reference/cli/api-keys/) for the full creation flow and principal selection.
 * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo.
 
 ---

src/content/docs/agent-platform/cloud-agents/quickstart.mdx

@@ -154,7 +154,7 @@ Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatical
 Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images.
 
 **Agent can't access repos**\
-Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`.
+Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using an agent API key, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`.
 
 **Not enough credits to run cloud agents**\
 Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents.

src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx

@@ -39,7 +39,7 @@ The Direct backend does not provide per-task container isolation. Each task runs
 * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team.
 * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`).
 * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli).
-* **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details.
+* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow.
 
 ---
 
@@ -50,7 +50,7 @@ The Direct backend does not provide per-task container isolation. Each task runs
 Export the API key so the worker can authenticate to Oz:
 
 ```bash
-export WARP_API_KEY="your_team_api_key"
+export WARP_API_KEY="your_agent_api_key"
 ```
 
 ### 2. Start the worker with the Direct backend

src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx

@@ -26,7 +26,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho
 * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team.
 * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work.
 * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`.
-* **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details.
+* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow.
 
 :::caution
 Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement.
@@ -46,10 +46,10 @@ docker info
 
 ## Set your API key
 
-Export your team API key so the worker can authenticate to Oz:
+Export your agent API key so the worker can authenticate to Oz:
 
 ```bash
-export WARP_API_KEY="your_team_api_key"
+export WARP_API_KEY="your_agent_api_key"
 ```
 
 ## Install and run the worker

src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx

@@ -38,7 +38,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho
   * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern).
   * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`.
 * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster.
-* **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details.
+* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow.
 
 ---
 
@@ -59,7 +59,7 @@ The chart does not create CRDs or cluster-scoped RBAC resources.
 ### 1. Set your API key and namespace
 
 ```bash
-export WARP_API_KEY="your_team_api_key"
+export WARP_API_KEY="your_agent_api_key"
 ```
 
 Create the namespace if it doesn't exist: