docs: cover Personal / Team / Agent API key types

[hongyi-chen]

Summary

Reframe the docs around cloud agents (the user-facing product term) rather than the internal "agent identity" / "Default Service Account" model. The goal is plain copy that mirrors what users actually see in the Oz web app, with no internal vocabulary leaking through.

The model the docs now describe:

• Personal API keys authenticate as you. Runs are attributed to your GitHub account and your credits.
• Agent API keys authenticate as a specific cloud agent — a named bot like deploy-bot or pr-reviewer that your team can share. Runs inherit the agent's secrets and skills, and the Oz dashboard attributes them to that bot.
• The team default cloud agent is just the default — no proper-noun name shown in concept pages.

Major rewrites

agent-platform/cloud-agents/agents.mdx

• Page renamed: Agent identities → Agents (matches the Agents page in the Oz web app).
• Opening rewritten to lead with what a cloud agent is and what binding a key gets you — no IAM service account analogy.
• Every agent identity / agent identities swapped to cloud agent / cloud agents (or just agent when context is unambiguous).
• Default Service Account proper-noun dropped from concept paragraphs; "team default" used generically.

reference/cli/api-keys.mdx

• Principals: personal or agent → Personal vs. agent keys. Each bullet is now framed by attribution (you vs. a named bot), not by what the agent flavor is missing.
• Agent identities power agent API keys section replaced with Cloud agents power agent API keys — 1–2 sentences plus the deploy-bot / pr-reviewer examples.
• The Default Service Account section and its legacy "team API key" callout are gone. The Warp desktop app's still-shown Team label gets one passing sentence inside the desktop-app creation step.
• Billing and GitHub authorization reframed around "the cloud agent the key is bound to".
• Best practices now says "automation you want attributed to a bot" instead of "no specific person behind it".

Sweep across the rest of the PR

• team-access-billing-and-identity.mdx — GitHub-auth step 3 and the Personal-tokens-vs-GitHub-App-tokens bullet drop the Default Service Account parentheticals and use cloud agent consistently.
• integrations/github-actions.mdx + integrations/quickstart-github-actions.mdx + reference/api-and-sdk/quickstart.mdx — Drop the awkward (no specific user behind them) parenthetical. Differentiate via attribution: "attribute runs to a cloud agent like pr-reviewer."
• self-hosting/{quickstart,managed-docker,managed-kubernetes,managed-direct,unmanaged}.mdx — Drop the explicit Default Service Account name in prereqs. Reads as: "Create an agent API key in the Oz web app. Use the team's default for self-hosting, or bind it to a custom cloud agent if you want the worker's runs attributed to a named bot."
• reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx — bound to an agent identity → bound to a cloud agent.

Out of scope (follow-up PR)

secrets.mdx, deployment-patterns.mdx, federate.mdx, and cli/index.mdx still use agent identity but weren't touched by this PR. Aligning them to cloud agent belongs in a follow-up sweep so this PR stays scoped to what it originally changed.

Validation

• style_lint --changed shows 9 remaining warnings, all confirmed false positives (one fewer than before since The Default Service Account header is gone).
• Grep confirms no agent identity / agent identities / Default Service Account remains in any file this PR touches.
• CI on the new commit (Build, link-check, audit; CodeQL; Vercel preview) — pushed and running.

Relationship to PR #141

PR #141 (Roland Huang's parallel Codex-harness branch) covers the same "team key → agent key" rename surface but with the find-and-replace approach this PR replaces. Recommend closing #141 in favor of this PR — coordination comment posted on #141.

Conversation: https://staging.warp.dev/conversation/70b07e4a-3574-40d5-98b3-8eb6926e83c0

Run: https://oz.staging.warp.dev/runs/019e65b0-299e-764d-adee-ba9155651f49

Plans:

• Reframe agent API key docs around agent identities (not as renamed team keys)
• Senior copywriter pass: rename to "cloud agents", drop Default Service Account, fix principal differentiation

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 27, 2026 8:25pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR updates the docs across cloud agents, self-hosting, CLI, API, and billing pages to distinguish Personal, Team, and Agent API key types and describe the different key-creation surfaces. I found no security-specific concerns in these docs-only changes, and the attached spec context says no approved repository spec was found.

Concerns

• The GitHub attribution wording in team-access-billing-and-identity.mdx now conflicts with the same section's GitHub App model by saying PRs and commits are attributed to an agent identity instead of the Oz by Warp GitHub App.
• One billing list item now duplicates the Enterprise billing bullet and mixes GitHub authorization into a billing-focused list; I left a cleanup suggestion inline.

Verdict

Found: 0 critical, 1 important, 1 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

💡 [SUGGESTION] Keep this billing list item scoped to Build/Max/Business; the Enterprise sentence duplicates the bullet immediately below, and GitHub App authorization is covered in the Team GitHub authorization section.

Suggested change

* **Team or agent API key, or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, these runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team and agent key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App.

* **Team or agent API key, or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap.

[hongyi-chen]

The substantive concerns (duplicate Enterprise bullet + GitHub authorization in a billing-focused list) were already cleaned up by the restructure in 51ea888 — the bullet at line 85 is now scoped purely to Build/Max/Business billing.

Intentionally keeping Agent API key rather than Team or agent API key here: the restructure unifies the terminology under a single name, with the legacy "team API key" equivalence covered once in api-keys.mdx#the-default-service-account instead of repeated inline on every page.

[oz-for-oss]

⚠️ [IMPORTANT] This conflicts with the same section's GitHub App explanation: PRs and commits created with a GitHub App token are attributed to the Oz by Warp GitHub App, while the agent identity is the Oz-side run identity.

Suggested change

	* **Team or agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. PRs and commits are attributed to the agent identity (or, for Warp-app-created team keys, the team's `Default Service Account`) rather than any individual user.
	* **Team or agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. PRs and commits are attributed to the Oz by Warp GitHub App rather than any individual user; the selected agent identity controls the run identity shown in Oz.

[hongyi-chen]

Good catch — fixed in 5245b2f. Now explicit that on GitHub, commits/PRs go to the Oz by Warp GitHub App bot user, while the bound agent identity is the run identity surfaced in the Oz dashboard. Applied the same disentanglement to team-access-billing-and-identity.mdx step 3 (line 143) and reference/cli/api-keys.mdx (line 82) which had the same conflation.

[hongyi-chen]

Is this still true?

[rachaelrenk]

Sidebar nav in the preview still shows "Agent identities" 🤔 should probably double check after merging, not sure why that's not reflected in the preview.

[rachaelrenk]

Worth also crosslinking to relevant pages for these last two bullets? Could link to

• https://docs.warp.dev/reference/cli/
• https://docs.warp.dev/agent-platform/cloud-agents/quickstart/

[rachaelrenk]

Also: I think this is the first time I've seen "Cloud Mode" used. What's that mean?

[rachaelrenk]

Suggested change

	Every team starts with a default cloud agent, which is what runs when an automation triggers a task with no other configuration. You can optionally create additional cloud agents through the Oz web app's **Agents** page or the public API — see [Managing cloud agents](#managing-cloud-agents) below.
	Every team starts with a default cloud agent, which is what runs when an automation triggers a task with no other configuration. You can optionally create additional cloud agents through the Oz web app's **Agents** page or the public API. See [Managing cloud agents](#managing-cloud-agents) below.

[rachaelrenk]

Suggested change

	In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:<uid>` when the CLI is authenticated as one, and [`oz federate issue-token`](/reference/cli/federate/) emits the same form in OIDC token subjects.
	In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:<uid>` when the CLI is authenticated as a service account, and [`oz federate issue-token`](/reference/cli/federate/) emits the same form in OIDC token subjects.

[rachaelrenk]

Added one suggested rewrite for the Managing cloud agents section to make the API details easier to scan.

[rachaelrenk]

This section may scan better if we separate the primary recommendation (use the UI for normal management), the API reference details, and the constraints. Moving the endpoint names into a compact table also makes the legacy /agent/identities path feel like API reference material instead of the conceptual lead-in.

Suggested change

	You can create, list, update, and delete cloud agents through the public API. The full request and response formats, including error codes, live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `updateAgent`, and `deleteAgent` under the **agent** tag.
	The endpoints behave as follows:
	* **Create** - `POST /agent/identities` with a `name` and optional `description`, `secrets`, and `skills`. Returns `201` with the new identity's `uid`, `name`, and `available` flag.
	* **List** - `GET /agent/identities` returns every agent identity on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit.
	* **Create** - `POST /agent/identities` with a `name` and optional `description`, `secrets`, and `skills`. Returns `201` with the new agent's `uid`, `name`, and `available` flag.
	* **List** - `GET /agent/identities` returns every cloud agent on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit.
	* **Update** - `PUT /agent/identities/{uid}` replaces individual fields. Omitting a field preserves the current value; passing an empty string or empty array clears it.
	* **Delete** - `DELETE /agent/identities/{uid}` soft-deletes the identity and atomically deletes every API key bound to it. The default agent identity cannot be deleted.
	* **Delete** - `DELETE /agent/identities/{uid}` soft-deletes the agent and atomically deletes every API key bound to it. The team's default agent cannot be deleted.
	### Caller requirements
	A few constraints apply across every endpoint:
	* **Team-scoped** - Agent identities belong to a team. The caller must be a member of exactly one team. If the caller is on zero teams or multiple teams, the request is rejected.
	* **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.
	* **Team-scoped** - Cloud agents belong to a team. The caller must be a member of exactly one team. If the caller is on zero teams or multiple teams, the request is rejected.
	* **Human callers only** - Only human users can create, update, or delete a cloud agent. A request authenticated as a cloud agent itself is rejected.
	* **Availability is enforced on use** - Over-plan-limit agents are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs.
	Use the [Oz web app's Agents page](/agent-platform/cloud-agents/oz-web-app/#agents) for day-to-day management. Use the public API when you need to create or update agents from scripts, CI/CD, or internal tooling. Full request and response formats, including error codes, live on the [API Reference](/api) page under the **agent** tag.
	<table><thead><tr><th width="120">Action</th><th>Endpoint</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Create</strong></td><td><code>POST /agent/identities</code></td><td>Creates a cloud agent with a <code>name</code> and optional <code>description</code>, <code>secrets</code>, and <code>skills</code>.</td></tr><tr><td><strong>List</strong></td><td><code>GET /agent/identities</code></td><td>Returns every cloud agent on the team, including the default, with an <code>available</code> flag for plan-limit status.</td></tr><tr><td><strong>Update</strong></td><td><code>PUT /agent/identities/{uid}</code></td><td>Replaces individual fields. Omitted fields stay unchanged; empty strings or arrays clear the field.</td></tr><tr><td><strong>Delete</strong></td><td><code>DELETE /agent/identities/{uid}</code></td><td>Soft-deletes the agent and deletes every API key bound to it. The team's default agent cannot be deleted.</td></tr></tbody></table>
	### Caller requirements
	Across all endpoints:
	* **Team-scoped** - Cloud agents belong to a team. The caller must be a member of exactly one team. If the caller is on zero teams or multiple teams, the request is rejected.
	* **Human callers only** - Only human users can create, update, or delete a cloud agent. A request authenticated as a cloud agent itself is rejected.
	* **Availability is enforced on use** - Over-plan-limit agents are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs.

[rachaelrenk]

Added a small wording suggestion for the API key type sentence.

[rachaelrenk]

Agree — this reads more clearly if we name both key types explicitly.

Suggested change

	Every API key is either **personal** or **agent**.
	Every API key is either a **personal API key** or an **agent API key**.

[rachaelrenk]

This is what I see in the UI:

Suggested change

	2. In the API Keys section, click **New API key**.
	2. In the API keys section, click **Generate new token**.

[rachaelrenk]

In the UI, this option is labelled "Type"

Suggested change

	3. Choose the principal:
	3. Choose the type:

[rachaelrenk]

We usually call this just the "Warp app", right?

Suggested change

	### From the Warp desktop app
	### From the Warp app

[rachaelrenk]

Not terrible, but this screenshot is outdated (doesn't show "Cloud platform" in the side nav, should recapture in ADE Berry theme for consistency)

[hongyi-chen]

Good catch — leaving this for a follow-up PR. Re-capturing the screenshot in the ADE Berry theme (and updating the surrounding "Cloud platform" sidenav layout) requires running the Warp app to take a fresh image, which is outside what I can do from this PR alone. I'll file a follow-up to recapture and swap in the new image.

[rachaelrenk]

Added a suggested rewrite for the API key billing/GitHub authorization section to make it more scannable.

[rachaelrenk]

This section is really about how the key type changes attribution, billing, and GitHub credentials. I think it would scan better with a more specific heading and parallel bullets for the two key types.

Suggested change

	How a run is billed and which GitHub permissions it gets depend on the type of key.
	Warp supports two types of API keys, each with different billing and identity behavior:
	**Personal keys.** Runs execute as you. On Build, Max, and Business plans, the credit waterfall is your plan-included credits, then your add-on credits — both scoped to you individually. On Enterprise plans, runs draw from the team-scoped credit pool. Code changes are attributed to your GitHub account.
	* **Personal API keys** - Cloud agent runs authenticate as you, just like running an agent from the Warp app or triggering one via Slack or Linear. On Build, Max, and Business plans, runs draw from your plan-included credits, then your add-on credits — both scoped to your individual user. On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms.
	* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted (insufficient credits error). With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App.
	**Agent keys.** Runs execute as a cloud agent on the team. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted (insufficient credits error). With auto-reload on, usage can trigger a reload on the owner's pool, subject to the team-wide monthly spend cap. On Enterprise plans, agent key runs draw from the team-scoped credit pool. For GitHub: when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, commits and PRs are opened by the **Oz by Warp** GitHub App. Without team GitHub authorization, agent keys can still run tasks that don't need to write to GitHub (analysis, monitoring, triage).
	Team API keys are useful for fully automated workflows, CI/CD pipelines, and scheduled tasks where no specific user context is needed. For the full credit waterfall and how it interacts with add-on credits, see [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) and [add-on credits](/support-and-community/plans-and-billing/add-on-credits/).
	For the full credit waterfall, see [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) and [add-on credits](/support-and-community/plans-and-billing/add-on-credits/).
	## How key type affects billing and GitHub access
	The key type determines who the run is attributed to, which credit pool is billed, and which GitHub credentials the agent can use.
	**Personal API keys**
	* Run as you.
	* On Build, Max, and Business plans, use your plan-included credits, then your add-on credits. On Enterprise plans, use the team-scoped credit pool.
	* Use your GitHub permissions. Code changes are attributed to your GitHub account.
	**Agent API keys**
	* Run as a cloud agent on your team.
	* On Build, Max, and Business plans, bill the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload on, usage can trigger a reload on the owner's pool, subject to the team-wide monthly spend cap. On Enterprise plans, use the team-scoped credit pool.
	* Use the **Oz by Warp** GitHub App when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured. Without team GitHub authorization, agent keys are still useful for tasks that don't need to write to GitHub, such as analysis, monitoring, or triage.
	For the full credit waterfall, see [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) and [add-on credits](/support-and-community/plans-and-billing/add-on-credits/).

[rachaelrenk]

I only see the masked suffix in the desktop app, not the web app.

[rachaelrenk]

I don't see "Created" or "Last used" dates in the Oz web app.

[rachaelrenk]

This is much more clear, thanks! Stamping with an approval, but I did leave some comments and suggested edits. I reviewed all copy and compared against the desktop and web app UIs: some of the procedural steps need updated, other suggestions are for readability/style. 🛸

[hongyi-chen]

@rachaelrenk thanks for the thorough review! Pushed 7ffe967 addressing your comments:

agents.mdx

• Em-dash → period in the "default cloud agent" paragraph (suggestion applied).
• Cross-linked the CLI and Warp app bullets to the Oz CLI and cloud agents quickstart, and removed the ambiguous "Cloud Mode" term in the Warp app bullet.
• Service account section now reads "authenticated as a service account" (suggestion applied).
• "Managing cloud agents" rewritten with a UI-first lead-in, a compact endpoint table, and a separate "Caller requirements" list (your suggestion applied).
• Also updated sidebar.ts to use the new Agents label (which is what was driving the stale "Agent identities" preview nav).

api-keys.mdx

• "Every API key is either a personal API key or an agent API key" (suggestion applied).
• Web app procedure now matches the live UI: Generate new token button + Choose the type (the UI's "Type" label).
• "From the Warp desktop app" → "From the Warp app".
• Replaced the billing section with the parallel bullet layout under "How key type affects billing and GitHub access" (your suggestion applied).
• Split the Managing API keys field list so masked Key suffix, Created, and Last used are documented as Warp-app-only fields.

Lingering "Agent identities" mentions
While I was at it, I cleaned up the remaining "agent identity" references in oz-web-app.mdx, overview.mdx, deployment-patterns.mdx, secrets.mdx, reference/cli/index.mdx, and reference/cli/federate.mdx to match the new terminology.

Screenshot recapture (api-key-management.png)
Left as a follow-up — replied inline. Recapturing the screenshot in the ADE Berry theme + current "Cloud platform" sidenav layout requires running the Warp app, which I'll do in a separate PR.