docs: cover Personal / Team / Agent API key types#143
Merged
Conversation
The Oz web app at oz.warp.dev/settings now uses 'Agent' API keys bound
to a specific agent identity, while the Warp desktop app still shows
'Team' (an Agent key bound to the team's Default Service Account is
functionally identical to a Team key for headless workflows).
Updates:
- reference/cli/api-keys.mdx: rewrite to cover all three key types,
describe per-surface UI (Oz web app vs. Warp desktop app), and call
out the Default Service Account / Team-key equivalence.
- Self-hosting prereqs (managed-{docker,kubernetes,direct}, quickstart,
unmanaged), integrations/quickstart-github-actions, api-and-sdk/
quickstart, reference/cli/quickstart: update 'create a team API key'
wording to mention both surfaces and link the new key-types section.
- integrations/github-actions.mdx: replace broken /reference/cli/
#generating-api-keys anchor with /reference/cli/api-keys/.
Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
After auditing PR #141 (parallel Codex run for REMOTE-1777), extend the sweep to the files that still said 'team API key' in places where the phrase should also acknowledge agent identity / Default Service Account keys created in the Oz web app. The Warp desktop app continues to label its key type 'Team' (and Jason is reverting NamedAgents in the client so it stays that way), so the wording becomes 'team or agent API key' rather than a pure rename. Touched files: - agent-platform/cloud-agents/agents.mdx - agent-platform/cloud-agents/team-access-billing-and-identity.mdx - agent-platform/cloud-agents/environments.mdx - agent-platform/cloud-agents/quickstart.mdx - agent-platform/cloud-agents/self-hosting/reference.mdx - enterprise/team-management/admin-panel.mdx - enterprise/support-and-resources/billing.mdx - reference/cli/integration-setup.mdx - reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx - reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx - support-and-community/plans-and-billing/credits.mdx - support-and-community/plans-and-billing/add-on-credits.mdx - support-and-community/plans-and-billing/pricing-faqs.mdx agents.mdx also gains the explicit 'Default Service Account' callout and the Warp-app-Team / Oz-web-app-Agent equivalence note. Co-Authored-By: Oz <oz-agent@warp.dev>
Contributor
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
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.mdxnow 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
|
|
||
| * **User-triggered runs on Build, Max, or Business** - Warp draws from any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user and are not shared across the team. | ||
| * **Team 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. | ||
| * **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. |
Contributor
There was a problem hiding this comment.
💡 [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. |
Collaborator
Author
There was a problem hiding this comment.
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.
|
|
||
| * **User-triggered runs** (personal API key, Slack, Linear, Warp app) - The agent authenticates as Oz acting on the triggering user's behalf. PRs and commits are attributed to that user. | ||
| * **Team API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. PRs and commits are not attributed to 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 agent identity (or, for Warp-app-created team keys, the team's `Default Service Account`) rather than any individual user. |
Contributor
There was a problem hiding this comment.
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. |
Collaborator
Author
There was a problem hiding this comment.
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.
…ntence After a final review, polish the wording for consistency: - Lowercase 'team API key' / 'agent API key' in prose (the concept). Reserve **bold** for the literal UI labels (Personal / Team / Agent). This matches how 'personal API key' was already styled. - Self-hosting prereqs: switch (`Agent` type) / (`Team` type) backticks to (**Agent** type) / (**Team** type) since these are UI labels per the style guide, not literal code/strings. - agents.mdx: 'called **Default Service Account**' → backticks, to match every other reference to the identity name in this PR. - team-access-billing-and-identity.mdx line 85: drop a redundant 'On Enterprise plans, these runs draw from the team-scoped credit pool...' sentence I had accidentally added to the Build/Max/Business bullet — that case is already covered by the Enterprise bullet right below it, and the GitHub-auth note duplicates content from the dedicated 'Team GitHub authorization' section. - api-keys.mdx 'Deleting API keys' wording: 'find it in either surface' was ambiguous; spell it out as 'either the Oz web app or the Warp desktop app's API Keys list'. No structural changes — pure textual edits, build behavior unchanged. Co-Authored-By: Oz <oz-agent@warp.dev>
…claimer Per user feedback: stop dual-naming (team or agent API key) and just use 'agent API key' everywhere. Add a single, prominent disclaimer at the top of api-keys.mdx noting that 'agent' used to be called 'team' and that the two behave identically. api-keys.mdx restructured: - Top of page: new :::note 'Naming change' disclaimer that explains the team \u2192 agent rename, the Default Service Account equivalence, and notes the Warp desktop app may still label the toggle 'Team'. - 'API key types' section: now lists only Personal and Agent (Team folded into Agent with the legacy-key note). - 'Creating API keys > From the Warp desktop app': simplified to a single step that says pick Personal, Agent, or Team; pointers back to the disclaimer for details.\n- Best practices and Managing sections: 'team or agent keys' \u2192\n 'agent keys'.\n\nAll other affected files: 'team or agent API key' / 'team and agent\nAPI key' / pre-existing 'team API key' \u2192 'agent API key'. The legacy\nterm only survives in:\n- The api-keys.mdx disclaimer.\n- One parenthetical in team-access-billing-and-identity.mdx that\n explicitly explains the legacy term for users who see it in the\n Warp desktop app.\n- analytics-api.mdx now says 'Agent API keys (including legacy team\n keys) are explicitly rejected'.\n- A historical changelog entry.\n\nCo-Authored-By: Oz <oz-agent@warp.dev>
Restructure the API keys page (reference/cli/api-keys.mdx) so it reads
as a principal-first conceptual page:
- Open with 'Principals: personal or agent' instead of leading with
the legacy naming-change disclaimer.
- Add 'Agent identities power agent API keys' with concrete worked
examples (deploy-bot, pr-reviewer, nightly-jobs) that show how
binding a key to an identity scopes its secrets, skills, and
attribution.
- Add 'The Default Service Account' as the no-config baseline, and
house the legacy 'team API key' note there as an inline callout.
- Split 'Creating an API key' into Oz web app (recommended, only
surface that exposes the named-identity picker) and Warp desktop
app (binds agent keys to the Default Service Account).
- Reframe billing and GitHub-authorization around the principal.
Strengthen agents.mdx (the agent-identity concept page):
- Add an IAM-service-account mental model paragraph.
- Strengthen the value-prop bullets with concrete deploy-bot /
pr-reviewer / nightly-jobs examples.
- Add 'Quickstart: create a custom agent identity' (5 steps:
create secret, POST /api/v1/agent/identities, generate bound key,
run agent, confirm attribution in the dashboard).
- Add a short 'Agent API keys' subsection cross-linking to
api-keys.mdx and naming the legacy 'team API key' equivalence.
Tighten the other affected docs so they defer to api-keys.mdx for
the personal-vs-agent guidance instead of repeating per-line
'Warp desktop app's equivalent toggle may still show Team' notes:
- self-hosting/{quickstart,managed-{docker,kubernetes,direct},
unmanaged}.mdx prereqs collapse to 'Create an agent API key in
the Oz web app bound to the Default Service Account (or a custom
agent identity for workflow-scoped attribution).'
- team-access-billing-and-identity.mdx GitHub-auth section
attributes commits to the bound agent identity (or to the
Default Service Account for legacy team keys).
- integrations/github-actions.mdx, integrations/quickstart-github-actions.mdx,
reference/api-and-sdk/quickstart.mdx, reference/cli/quickstart.mdx
shorten inline notes to point at api-keys.mdx and link agents.mdx.
- unmanaged.mdx: wrap the oz agent run CLI command in backticks in
the description so it reads as a literal command (also clears the
OZ-TERM style lint warning).
Co-Authored-By: Oz <oz-agent@warp.dev>
Addresses oz-for-oss review on PR #143 (discussion r3307282172): the docs incorrectly claimed that PRs and commits opened via the Oz by Warp GitHub App were attributed to the bound agent identity. In reality: - On GitHub, commits and pull requests opened with a GitHub App installation token are attributed to the Oz by Warp GitHub App's bot user — not to the agent identity the API key is bound to. - The agent identity is the Oz-side run identity. It controls run filtering, audit attribution, and which secrets/skills the run inherits — but it does not appear as a commit author on GitHub. Fix the three places that had the conflation: - team-access-billing-and-identity.mdx "Setting up team GitHub authorization" step 3 (line 143). - team-access-billing-and-identity.mdx "Personal tokens vs. GitHub App tokens" bullet (line 159). - reference/cli/api-keys.mdx "Billing and GitHub authorization" agent-keys paragraph (line 82). Each now explicitly separates 'on GitHub, the GitHub App is the author' from 'in the Oz dashboard, the agent identity is the run attribution'. The companion SUGGESTION (r3307282159) about the billing bullet at team-access-billing-and-identity.mdx line 85 was already addressed by the earlier restructure commit 51ea888 — that bullet no longer duplicates the Enterprise sentence or mixes GitHub authorization into the billing-focused list. The 'Team or' prefix in the reviewer's suggested wording is intentionally not adopted, because the restructure unifies the terminology under 'agent API key' (with the legacy 'team API key' equivalence covered once in api-keys.mdx#the-default-service-account). Co-Authored-By: Oz <oz-agent@warp.dev>
Per feedback that 'workflow-scoped identity for headless runs' is hard to parse, sweep the PR's affected files and replace jargon with plain-English equivalents: - 'workflow-scoped identity for headless runs' \u2192 'automated runs (no specific user behind them)' or 'automated runs' depending on context. - 'headless run / workflow / caller / automation' \u2192 'automated run / workflow / caller'. - 'workflow-scoped attribution' \u2192 'so runs are attributed to a specific bot'. Files touched: integrations/github-actions.mdx, integrations/quickstart-github-actions.mdx, reference/cli/api-keys.mdx (Principals, Default Service Account, Creating an API key from the Oz web app, Best practices), agents.mdx (mental-model paragraph, How agent identities work, Agent API keys, Running as an agent identity), reference/api-and-sdk/quickstart.mdx, self-hosting/unmanaged.mdx, team-access-billing-and-identity.mdx (credit usage bullet). Kept the industry-standard term 'headless servers' in the api-keys.mdx opening line (CI pipelines, headless servers, VMs, Codespaces) since that's a well-understood compound term. Co-Authored-By: Oz <oz-agent@warp.dev>
…e Account, fix principal differentiation
Address user feedback on the prior framing:
1. "agent identity" sounds abstract; just call them cloud agents
2. "Default Service Account" is an internal implementation detail
3. "(no specific user behind them)" is an awkward way to differentiate
Major rewrites:
agents.mdx — Rename to 'Agents'. Drop the IAM service account
analogy. Open with what a cloud agent is and what binding a key
to it gets you. Replace every 'agent identity'/'identities'
with 'cloud agent'/'cloud agents' (or just 'agent' when
unambiguous). Drop standalone 'Default Service Account'
mentions; the team default is referenced generically.
reference/cli/api-keys.mdx — Rename 'Principals: personal or
agent' → 'Personal vs. agent keys'. Replace 'Agent identities
power agent API keys' section with 'Cloud agents power agent
API keys' (1-2 sentences plus deploy-bot/pr-reviewer examples).
Delete 'The Default Service Account' section and its legacy
'team API key' callout entirely; the desktop-app creation step
gets one passing sentence about the **Team** toggle. Best
practices and Billing/GitHub-auth reframed around 'cloud agent
the key is bound to'.
Sweep across the rest of the PR's files (10 total):
- team-access-billing-and-identity.mdx: GitHub-auth step 3 and
the Personal-tokens-vs-GitHub-App-tokens bullet drop
'Default Service Account' and use 'cloud agent'.
- integrations/github-actions.mdx + 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; the team default is mentioned
generically.
- external-authentication-required.mdx: 'bound to an agent
identity' → 'bound to a cloud agent'.
Out of scope for this PR but flagged in the plan: secrets.mdx,
deployment-patterns.mdx, federate.mdx, cli/index.mdx use 'agent
identity' but were not touched here. Follow-up PR.
style_lint --changed shows 9 remaining warnings, all confirmed
false positives (one fewer than before since the Default
Service Account header was removed).
Co-Authored-By: Oz <oz-agent@warp.dev>
…terized by their triggers
Address user feedback that:
1. deploy-bot / pr-reviewer / nightly-jobs examples were peppered everywhere
2. 'named bot' framing is wrong - a cloud agent is just an agent
that runs in the cloud, characterized by its trigger
3. Docs shouldn't push the named-cloud-agent feature
Rewrites:
agents.mdx - Reframe entirely around triggers. The opening now
explains cloud agents as how Warp runs scheduled jobs,
integration triggers, CI/CD automation, and API-driven tasks.
'How cloud agents get triggered' replaces the value-prop bullets.
The 'Quickstart: create a custom agent identity' section is gone
- creating named cloud agents with attached secrets and skills
is an advanced configuration, not a headline feature. The
Managing cloud agents API reference stays for completeness.
api-keys.mdx - Simpler 'Personal vs. agent keys' framing:
- Personal: runs attributed to you
- Agent: runs as a cloud agent on your team, used for scheduled
jobs, integrations, SDK-triggered runs, and other automation
that isn't tied to a specific user
Dropped the entire 'Cloud agents power agent API keys' section
that listed name/secrets/skills as headline features. Best
practices no longer pushes 'pick a cloud agent that matches the
workflow'.
Sweep:
- github-actions.mdx, quickstart-github-actions.mdx: 'attribute
runs to a cloud agent like pr-reviewer' \u2192 'run as a cloud
agent on your team'
- self-hosting/{quickstart,managed-docker,managed-kubernetes,
managed-direct,unmanaged}.mdx: dropped 'use the team's default,
or bind it to a custom cloud agent if you want the worker's
runs attributed to a named bot' \u2192 just 'Create one in the Oz
web app so the worker can authenticate'
All deploy-bot / pr-reviewer / nightly-jobs example names are now
removed from PR-touched files. Grep confirms no occurrences.
style_lint --changed: 8 false positives (down from 9 - the
deploy-bot UI-BACKTICK warning is gone).
Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
commented
May 27, 2026
| ### How are cloud agent runs on team plans billed when no individual user triggered them? | ||
|
|
||
| Some cloud agent runs aren't initiated by a specific team member — for example, scheduled runs or runs triggered through a team API key. On self-serve plans (Build, Max, Business), these runs are billed to the **team owner**. | ||
| Some cloud agent runs aren't initiated by a specific team member — for example, scheduled runs or runs triggered through an agent API key. On self-serve plans (Build, Max, Business), these runs are billed to the **team owner**. |
Collaborator
Author
There was a problem hiding this comment.
Is this still true?
Contributor
There was a problem hiding this comment.
@tylerlam-warp would know for sure, but I believe so
There was a problem hiding this comment.
Yeah this is still true. There's some nuance here that might be worth being specific about, but if you want to be specific:
Some cloud agent runs aren't initiated by a specific team member — for example, scheduled runs or runs triggered through an agent API key. On self-serve plans (Build, Max, Business), these runs can be billed to team-scoped credits. If the team has no team-scoped credits, the runs are billed to the **team owner**.
rachaelrenk
reviewed
May 27, 2026
| automation, and API-driven tasks against your team's environments. | ||
| sidebar: | ||
| label: "Agent identities" | ||
| label: "Agents" |
Contributor
There was a problem hiding this comment.
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
reviewed
May 27, 2026
rachaelrenk
reviewed
May 27, 2026
| * **Last used** - When the key was last used for authentication | ||
| * **Expires at** - The key's expiration date, or "Never" if it doesn't expire | ||
| * **Name** — The name you assigned when creating the key. | ||
| * **Key** — A masked suffix (`wk-**xxxx`) to help identify the key. |
Contributor
There was a problem hiding this comment.
I only see the masked suffix in the desktop app, not the web app.
rachaelrenk
reviewed
May 27, 2026
Comment on lines
+86
to
+87
| * **Created** — When the key was created. | ||
| * **Last used** — When the key was last used for authentication. |
Contributor
There was a problem hiding this comment.
I don't see "Created" or "Last used" dates in the Oz web app.
rachaelrenk
approved these changes
May 27, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
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. 🛸
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
agents.mdx:
- Replace em-dash with period in default cloud agent paragraph
- Cross-link CLI and Warp app bullets to Oz CLI and cloud agents quickstart
- Remove ambiguous 'Cloud Mode' term in the Warp app bullet
- Clarify Service accounts section: 'authenticated as a service account'
- Restructure 'Managing cloud agents' with UI-first guidance, endpoint
table, and separate caller-requirements list
api-keys.mdx:
- Name both key types explicitly ('personal API key' / 'agent API key')
- Update Oz web app procedure to match the live UI:
- 'Generate new token' button label
- 'Choose the type:' (matches the 'Type' label in the UI)
- Rename 'From the Warp desktop app' heading to 'From the Warp app'
- Replace 'Billing and GitHub authorization' section with parallel
bullet lists under a more specific 'How key type affects billing and
GitHub access' heading
- Split the managed-keys list so masked suffix, Created, and Last used
are documented as Warp-app-only fields
Sidebar / cross-page consistency:
- Fix sidebar label from 'Agent identities' to 'Agents' so the nav
matches the renamed page
- Update remaining 'agent identity' / 'Agent identities' references in
oz-web-app.mdx, overview.mdx, deployment-patterns.mdx, secrets.mdx,
reference/cli/index.mdx, and reference/cli/federate.mdx to 'cloud
agent(s)' to match the new terminology
Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
|
@rachaelrenk thanks for the thorough review! Pushed 7ffe967 addressing your comments:
Lingering "Agent identities" mentions Screenshot recapture ( |
Followup pass after Rachael's review: comment 3312118944 normalized the heading to 'From the Warp app'. Two body sentences still read 'Warp desktop app' — bring them in line with that wording. - agents.mdx: 'Warp app' bullet body now says 'the Warp app' instead of 'the Warp desktop app'. - api-keys.mdx: 'Deleting API keys' section now says 'the Warp app's API Keys list' instead of 'the Warp desktop app's API Keys list'. Co-Authored-By: Oz <oz-agent@warp.dev>
bnavetta
approved these changes
Jun 1, 2026
| * **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) so the worker can authenticate to Oz. See [API Keys](/reference/cli/api-keys/) for the full creation flow. |
Contributor
There was a problem hiding this comment.
We should call out here that you can create the API key as any agent, and it doesn't restrict which ones can use the worker. Same for the other backends as well
@ianhodge it probably also makes sense to lift the self-hosted worker restriction that only agent API keys work. Going to track that
| * `--share user@example.com:edit` — Give a specific user read/write access. | ||
|
|
||
| The `--share` flag can be repeated to combine multiple sharing targets. If you authenticate with a team API key, agents are automatically team-scoped. | ||
| The `--share` flag can be repeated to combine multiple sharing targets. If you authenticate with an agent API key, agents are automatically team-scoped. |
Contributor
There was a problem hiding this comment.
Suggested change
| The `--share` flag can be repeated to combine multiple sharing targets. If you authenticate with an agent API key, agents are automatically team-scoped. | |
| The `--share` flag can be repeated to combine multiple sharing targets. If you authenticate with an agent API key, runs are automatically team-scoped. |
| --- | ||
|
|
||
| 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. | ||
| A **cloud agent** is an agent that runs in Warp's cloud (or on a self-hosted worker) instead of on your local machine. Cloud agents are how Warp powers automation: scheduled jobs, Slack and Linear integrations, GitHub Actions, the Oz API and SDKs, and `oz agent run-cloud` from the CLI all execute as cloud agents. |
Contributor
There was a problem hiding this comment.
Technically, these can also all run as individual users. I think it's still fair to say that you should use a cloud agent when you want to give an automation its own settings and permissions, instead of acting as a user on your team.
| * **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. See [Integrations](/agent-platform/cloud-agents/integrations/). | ||
| * **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [Oz API](/reference/api-and-sdk/). | ||
| * **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [Oz CLI](/reference/cli/). | ||
| * **Warp app** — The `/cloud-agent` slash command in the Warp app. See the [cloud agents quickstart](/agent-platform/cloud-agents/quickstart/). |
Contributor
There was a problem hiding this comment.
This will always run as the individual user, not an agent
| * **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. | ||
| * **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. | ||
| <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> |
Contributor
There was a problem hiding this comment.
nit: more readable to use a Markdown table here?
| Across all endpoints: | ||
|
|
||
| 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. | ||
| * **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. |
Contributor
There was a problem hiding this comment.
I think we can remove this since there's currently no way to end up on multiple teams
| ### How are cloud agent runs on team plans billed when no individual user triggered them? | ||
|
|
||
| Some cloud agent runs aren't initiated by a specific team member — for example, scheduled runs or runs triggered through a team API key. On self-serve plans (Build, Max, Business), these runs are billed to the **team owner**. | ||
| Some cloud agent runs aren't initiated by a specific team member — for example, scheduled runs or runs triggered through an agent API key. On self-serve plans (Build, Max, Business), these runs are billed to the **team owner**. |
Contributor
There was a problem hiding this comment.
@tylerlam-warp would know for sure, but I believe so
4 tasks
* docs: align agent UID OpenAPI wording Co-Authored-By: Oz <oz-agent@warp.dev> * docs: lint deprecated agent identity terminology Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>
- agents.mdx: reframe opening around giving automation its own settings/permissions; clarify when runs execute as a cloud agent vs the calling user (drop Warp app /cloud-agent bullet, which always runs as the user); convert endpoints HTML table to Markdown; remove the Team-scoped caller-requirement bullet - self-hosting (managed-direct/docker/kubernetes, quickstart, reference): note the agent API key can be bound to any cloud agent and doesn't restrict which agents run on the worker - unmanaged.mdx: 'agents' -> 'runs' are automatically team-scoped Co-Authored-By: Oz <oz-agent@warp.dev>
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Resolved 4 conflicts by keeping the branch's agent-API-key terminology/restructure while preserving main's newly added content: - api-keys.mdx: kept the restructured Personal/Agent billing bullets - team-access-billing-and-identity.mdx: 'Agent API key' wording + main's spend-cap clause - quickstart.mdx: 'agent API key' wording + main's external_authentication_required / not_authorized crosslinks - insufficient-credits.mdx: kept the branch's more specific frontmatter description Co-Authored-By: Oz <oz-agent@warp.dev>
Integrates remote web-edit commit 88b6866. That edit accidentally duplicated the 'How key type affects billing and GitHub access' heading and intro paragraph; removed the duplication and restored the blank line before '## Authenticating with API keys'. Co-Authored-By: Oz <oz-agent@warp.dev>
- bring-your-own-llm.mdx: 'agent identity' -> 'cloud agent' (term carried in from main) - agents.mdx: reframe frontmatter description to match the reworked opening (own settings/permissions vs acting as a user) Co-Authored-By: Oz <oz-agent@warp.dev>
Revert the frontmatter description change from the audit pass per preference; the reworked body opening is unchanged. Co-Authored-By: Oz <oz-agent@warp.dev>
jasonkeung
added a commit
to warpdotdev/warp
that referenced
this pull request
Jun 3, 2026
## Description Adds a `Learn more` link to the agent API key helper text in the create API key modal. The link points to the docs page anchor that will explain personal vs. agent API keys after warpdotdev/docs#143 lands. ## Linked Issue No linked issue; requested from Slack. - [ ] The linked issue is labeled `ready-to-spec` or `ready-to-implement`. - [ ] Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes). ## Testing - `cargo fmt --manifest-path /workspace/warp/app/Cargo.toml -- /workspace/warp/app/src/settings_view/platform/create_api_key_modal.rs` - `cargo check --manifest-path /workspace/warp/Cargo.toml -p warp --lib` - [ ] I have manually tested my changes locally with `./script/run` ### Screenshots / Videos Not included; this is a text/link-only modal change and was validated with a targeted compile check in the sandbox. ## Agent Mode - [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode CHANGELOG-NONE _Conversation: https://staging.warp.dev/conversation/51bd7b68-6b31-4e28-ac1a-c9876a736b8b_ _Run: https://oz.staging.warp.dev/runs/019e84f7-7104-7aa2-94e5-f832e226eb54_ _This PR was generated with [Oz](https://warp.dev/oz)._ Co-authored-by: Oz <oz-agent@warp.dev>
wanghaozi
pushed a commit
to wanghaozi/docs
that referenced
this pull request
Jun 3, 2026
* Document Personal / Team / Agent API key types
The Oz web app at oz.warp.dev/settings now uses 'Agent' API keys bound
to a specific agent identity, while the Warp desktop app still shows
'Team' (an Agent key bound to the team's Default Service Account is
functionally identical to a Team key for headless workflows).
Updates:
- reference/cli/api-keys.mdx: rewrite to cover all three key types,
describe per-surface UI (Oz web app vs. Warp desktop app), and call
out the Default Service Account / Team-key equivalence.
- Self-hosting prereqs (managed-{docker,kubernetes,direct}, quickstart,
unmanaged), integrations/quickstart-github-actions, api-and-sdk/
quickstart, reference/cli/quickstart: update 'create a team API key'
wording to mention both surfaces and link the new key-types section.
- integrations/github-actions.mdx: replace broken /reference/cli/
#generating-api-keys anchor with /reference/cli/api-keys/.
Co-Authored-By: Oz <oz-agent@warp.dev>
* Broaden API key wording across billing, GitHub auth, and error docs
After auditing PR warpdotdev#141 (parallel Codex run for REMOTE-1777), extend the
sweep to the files that still said 'team API key' in places where the
phrase should also acknowledge agent identity / Default Service Account
keys created in the Oz web app. The Warp desktop app continues to label
its key type 'Team' (and Jason is reverting NamedAgents in the client
so it stays that way), so the wording becomes 'team or agent API key'
rather than a pure rename.
Touched files:
- agent-platform/cloud-agents/agents.mdx
- agent-platform/cloud-agents/team-access-billing-and-identity.mdx
- agent-platform/cloud-agents/environments.mdx
- agent-platform/cloud-agents/quickstart.mdx
- agent-platform/cloud-agents/self-hosting/reference.mdx
- enterprise/team-management/admin-panel.mdx
- enterprise/support-and-resources/billing.mdx
- reference/cli/integration-setup.mdx
- reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx
- reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx
- support-and-community/plans-and-billing/credits.mdx
- support-and-community/plans-and-billing/add-on-credits.mdx
- support-and-community/plans-and-billing/pricing-faqs.mdx
agents.mdx also gains the explicit 'Default Service Account' callout
and the Warp-app-Team / Oz-web-app-Agent equivalence note.
Co-Authored-By: Oz <oz-agent@warp.dev>
* Final pass: normalize key-type casing, remove redundant Enterprise sentence
After a final review, polish the wording for consistency:
- Lowercase 'team API key' / 'agent API key' in prose (the concept).
Reserve **bold** for the literal UI labels (Personal / Team / Agent).
This matches how 'personal API key' was already styled.
- Self-hosting prereqs: switch (`Agent` type) / (`Team` type) backticks
to (**Agent** type) / (**Team** type) since these are UI labels per the
style guide, not literal code/strings.
- agents.mdx: 'called **Default Service Account**' → backticks, to match
every other reference to the identity name in this PR.
- team-access-billing-and-identity.mdx line 85: drop a redundant
'On Enterprise plans, these runs draw from the team-scoped credit
pool...' sentence I had accidentally added to the Build/Max/Business
bullet — that case is already covered by the Enterprise bullet right
below it, and the GitHub-auth note duplicates content from the
dedicated 'Team GitHub authorization' section.
- api-keys.mdx 'Deleting API keys' wording: 'find it in either surface'
was ambiguous; spell it out as 'either the Oz web app or the Warp
desktop app's API Keys list'.
No structural changes — pure textual edits, build behavior unchanged.
Co-Authored-By: Oz <oz-agent@warp.dev>
* Switch to 'agent API key' throughout, with single team\u2192agent disclaimer
Per user feedback: stop dual-naming (team or agent API key) and just use
'agent API key' everywhere. Add a single, prominent disclaimer at the
top of api-keys.mdx noting that 'agent' used to be called 'team' and
that the two behave identically.
api-keys.mdx restructured:
- Top of page: new :::note 'Naming change' disclaimer that explains the
team \u2192 agent rename, the Default Service Account equivalence, and
notes the Warp desktop app may still label the toggle 'Team'.
- 'API key types' section: now lists only Personal and Agent (Team
folded into Agent with the legacy-key note).
- 'Creating API keys > From the Warp desktop app': simplified to a
single step that says pick Personal, Agent, or Team; pointers back
to the disclaimer for details.\n- Best practices and Managing sections: 'team or agent keys' \u2192\n 'agent keys'.\n\nAll other affected files: 'team or agent API key' / 'team and agent\nAPI key' / pre-existing 'team API key' \u2192 'agent API key'. The legacy\nterm only survives in:\n- The api-keys.mdx disclaimer.\n- One parenthetical in team-access-billing-and-identity.mdx that\n explicitly explains the legacy term for users who see it in the\n Warp desktop app.\n- analytics-api.mdx now says 'Agent API keys (including legacy team\n keys) are explicitly rejected'.\n- A historical changelog entry.\n\nCo-Authored-By: Oz <oz-agent@warp.dev>
* Reframe agent API key docs around agent identities
Restructure the API keys page (reference/cli/api-keys.mdx) so it reads
as a principal-first conceptual page:
- Open with 'Principals: personal or agent' instead of leading with
the legacy naming-change disclaimer.
- Add 'Agent identities power agent API keys' with concrete worked
examples (deploy-bot, pr-reviewer, nightly-jobs) that show how
binding a key to an identity scopes its secrets, skills, and
attribution.
- Add 'The Default Service Account' as the no-config baseline, and
house the legacy 'team API key' note there as an inline callout.
- Split 'Creating an API key' into Oz web app (recommended, only
surface that exposes the named-identity picker) and Warp desktop
app (binds agent keys to the Default Service Account).
- Reframe billing and GitHub-authorization around the principal.
Strengthen agents.mdx (the agent-identity concept page):
- Add an IAM-service-account mental model paragraph.
- Strengthen the value-prop bullets with concrete deploy-bot /
pr-reviewer / nightly-jobs examples.
- Add 'Quickstart: create a custom agent identity' (5 steps:
create secret, POST /api/v1/agent/identities, generate bound key,
run agent, confirm attribution in the dashboard).
- Add a short 'Agent API keys' subsection cross-linking to
api-keys.mdx and naming the legacy 'team API key' equivalence.
Tighten the other affected docs so they defer to api-keys.mdx for
the personal-vs-agent guidance instead of repeating per-line
'Warp desktop app's equivalent toggle may still show Team' notes:
- self-hosting/{quickstart,managed-{docker,kubernetes,direct},
unmanaged}.mdx prereqs collapse to 'Create an agent API key in
the Oz web app bound to the Default Service Account (or a custom
agent identity for workflow-scoped attribution).'
- team-access-billing-and-identity.mdx GitHub-auth section
attributes commits to the bound agent identity (or to the
Default Service Account for legacy team keys).
- integrations/github-actions.mdx, integrations/quickstart-github-actions.mdx,
reference/api-and-sdk/quickstart.mdx, reference/cli/quickstart.mdx
shorten inline notes to point at api-keys.mdx and link agents.mdx.
- unmanaged.mdx: wrap the oz agent run CLI command in backticks in
the description so it reads as a literal command (also clears the
OZ-TERM style lint warning).
Co-Authored-By: Oz <oz-agent@warp.dev>
* Disentangle GitHub-side commit attribution from Oz-side run identity
Addresses oz-for-oss review on PR warpdotdev#143 (discussion r3307282172): the
docs incorrectly claimed that PRs and commits opened via the Oz by
Warp GitHub App were attributed to the bound agent identity. In
reality:
- On GitHub, commits and pull requests opened with a GitHub App
installation token are attributed to the Oz by Warp GitHub App's
bot user — not to the agent identity the API key is bound to.
- The agent identity is the Oz-side run identity. It controls run
filtering, audit attribution, and which secrets/skills the run
inherits — but it does not appear as a commit author on GitHub.
Fix the three places that had the conflation:
- team-access-billing-and-identity.mdx "Setting up team GitHub
authorization" step 3 (line 143).
- team-access-billing-and-identity.mdx "Personal tokens vs. GitHub
App tokens" bullet (line 159).
- reference/cli/api-keys.mdx "Billing and GitHub authorization"
agent-keys paragraph (line 82).
Each now explicitly separates 'on GitHub, the GitHub App is the
author' from 'in the Oz dashboard, the agent identity is the run
attribution'.
The companion SUGGESTION (r3307282159) about the billing bullet at
team-access-billing-and-identity.mdx line 85 was already addressed
by the earlier restructure commit 51ea888 — that bullet no longer
duplicates the Enterprise sentence or mixes GitHub authorization
into the billing-focused list. The 'Team or' prefix in the
reviewer's suggested wording is intentionally not adopted, because
the restructure unifies the terminology under 'agent API key'
(with the legacy 'team API key' equivalence covered once in
api-keys.mdx#the-default-service-account).
Co-Authored-By: Oz <oz-agent@warp.dev>
* Replace 'headless' / 'workflow-scoped' jargon with plain 'automated'
Per feedback that 'workflow-scoped identity for headless runs' is
hard to parse, sweep the PR's affected files and replace jargon
with plain-English equivalents:
- 'workflow-scoped identity for headless runs' \u2192 'automated runs
(no specific user behind them)' or 'automated runs' depending
on context.
- 'headless run / workflow / caller / automation' \u2192 'automated
run / workflow / caller'.
- 'workflow-scoped attribution' \u2192 'so runs are attributed to a
specific bot'.
Files touched: integrations/github-actions.mdx,
integrations/quickstart-github-actions.mdx, reference/cli/api-keys.mdx
(Principals, Default Service Account, Creating an API key from the
Oz web app, Best practices), agents.mdx (mental-model paragraph,
How agent identities work, Agent API keys, Running as an agent
identity), reference/api-and-sdk/quickstart.mdx,
self-hosting/unmanaged.mdx, team-access-billing-and-identity.mdx
(credit usage bullet).
Kept the industry-standard term 'headless servers' in the
api-keys.mdx opening line (CI pipelines, headless servers, VMs,
Codespaces) since that's a well-understood compound term.
Co-Authored-By: Oz <oz-agent@warp.dev>
* Senior copywriter pass: rename to 'cloud agents', drop Default Service Account, fix principal differentiation
Address user feedback on the prior framing:
1. "agent identity" sounds abstract; just call them cloud agents
2. "Default Service Account" is an internal implementation detail
3. "(no specific user behind them)" is an awkward way to differentiate
Major rewrites:
agents.mdx — Rename to 'Agents'. Drop the IAM service account
analogy. Open with what a cloud agent is and what binding a key
to it gets you. Replace every 'agent identity'/'identities'
with 'cloud agent'/'cloud agents' (or just 'agent' when
unambiguous). Drop standalone 'Default Service Account'
mentions; the team default is referenced generically.
reference/cli/api-keys.mdx — Rename 'Principals: personal or
agent' → 'Personal vs. agent keys'. Replace 'Agent identities
power agent API keys' section with 'Cloud agents power agent
API keys' (1-2 sentences plus deploy-bot/pr-reviewer examples).
Delete 'The Default Service Account' section and its legacy
'team API key' callout entirely; the desktop-app creation step
gets one passing sentence about the **Team** toggle. Best
practices and Billing/GitHub-auth reframed around 'cloud agent
the key is bound to'.
Sweep across the rest of the PR's files (10 total):
- team-access-billing-and-identity.mdx: GitHub-auth step 3 and
the Personal-tokens-vs-GitHub-App-tokens bullet drop
'Default Service Account' and use 'cloud agent'.
- integrations/github-actions.mdx + 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; the team default is mentioned
generically.
- external-authentication-required.mdx: 'bound to an agent
identity' → 'bound to a cloud agent'.
Out of scope for this PR but flagged in the plan: secrets.mdx,
deployment-patterns.mdx, federate.mdx, cli/index.mdx use 'agent
identity' but were not touched here. Follow-up PR.
style_lint --changed shows 9 remaining warnings, all confirmed
false positives (one fewer than before since the Default
Service Account header was removed).
Co-Authored-By: Oz <oz-agent@warp.dev>
* Drop bot-name examples and named-bot framing; cloud agents are characterized by their triggers
Address user feedback that:
1. deploy-bot / pr-reviewer / nightly-jobs examples were peppered everywhere
2. 'named bot' framing is wrong - a cloud agent is just an agent
that runs in the cloud, characterized by its trigger
3. Docs shouldn't push the named-cloud-agent feature
Rewrites:
agents.mdx - Reframe entirely around triggers. The opening now
explains cloud agents as how Warp runs scheduled jobs,
integration triggers, CI/CD automation, and API-driven tasks.
'How cloud agents get triggered' replaces the value-prop bullets.
The 'Quickstart: create a custom agent identity' section is gone
- creating named cloud agents with attached secrets and skills
is an advanced configuration, not a headline feature. The
Managing cloud agents API reference stays for completeness.
api-keys.mdx - Simpler 'Personal vs. agent keys' framing:
- Personal: runs attributed to you
- Agent: runs as a cloud agent on your team, used for scheduled
jobs, integrations, SDK-triggered runs, and other automation
that isn't tied to a specific user
Dropped the entire 'Cloud agents power agent API keys' section
that listed name/secrets/skills as headline features. Best
practices no longer pushes 'pick a cloud agent that matches the
workflow'.
Sweep:
- github-actions.mdx, quickstart-github-actions.mdx: 'attribute
runs to a cloud agent like pr-reviewer' \u2192 'run as a cloud
agent on your team'
- self-hosting/{quickstart,managed-docker,managed-kubernetes,
managed-direct,unmanaged}.mdx: dropped 'use the team's default,
or bind it to a custom cloud agent if you want the worker's
runs attributed to a named bot' \u2192 just 'Create one in the Oz
web app so the worker can authenticate'
All deploy-bot / pr-reviewer / nightly-jobs example names are now
removed from PR-touched files. Grep confirms no occurrences.
style_lint --changed: 8 false positives (down from 9 - the
deploy-bot UI-BACKTICK warning is gone).
Co-Authored-By: Oz <oz-agent@warp.dev>
* Update src/content/docs/agent-platform/cloud-agents/agents.mdx
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
* Address Rachael's review feedback
agents.mdx:
- Replace em-dash with period in default cloud agent paragraph
- Cross-link CLI and Warp app bullets to Oz CLI and cloud agents quickstart
- Remove ambiguous 'Cloud Mode' term in the Warp app bullet
- Clarify Service accounts section: 'authenticated as a service account'
- Restructure 'Managing cloud agents' with UI-first guidance, endpoint
table, and separate caller-requirements list
api-keys.mdx:
- Name both key types explicitly ('personal API key' / 'agent API key')
- Update Oz web app procedure to match the live UI:
- 'Generate new token' button label
- 'Choose the type:' (matches the 'Type' label in the UI)
- Rename 'From the Warp desktop app' heading to 'From the Warp app'
- Replace 'Billing and GitHub authorization' section with parallel
bullet lists under a more specific 'How key type affects billing and
GitHub access' heading
- Split the managed-keys list so masked suffix, Created, and Last used
are documented as Warp-app-only fields
Sidebar / cross-page consistency:
- Fix sidebar label from 'Agent identities' to 'Agents' so the nav
matches the renamed page
- Update remaining 'agent identity' / 'Agent identities' references in
oz-web-app.mdx, overview.mdx, deployment-patterns.mdx, secrets.mdx,
reference/cli/index.mdx, and reference/cli/federate.mdx to 'cloud
agent(s)' to match the new terminology
Co-Authored-By: Oz <oz-agent@warp.dev>
* Use 'Warp app' consistently in two remaining spots
Followup pass after Rachael's review: comment 3312118944 normalized the
heading to 'From the Warp app'. Two body sentences still read 'Warp
desktop app' — bring them in line with that wording.
- agents.mdx: 'Warp app' bullet body now says 'the Warp app' instead of
'the Warp desktop app'.
- api-keys.mdx: 'Deleting API keys' section now says 'the Warp app's
API Keys list' instead of 'the Warp desktop app's API Keys list'.
Co-Authored-By: Oz <oz-agent@warp.dev>
* docs: align agent UID wording + terminology + style guide (warpdotdev#168)
* docs: align agent UID OpenAPI wording
Co-Authored-By: Oz <oz-agent@warp.dev>
* docs: lint deprecated agent identity terminology
Co-Authored-By: Oz <oz-agent@warp.dev>
---------
Co-authored-by: Oz <oz-agent@warp.dev>
* docs: address Ben's review feedback on cloud agents and API keys
- agents.mdx: reframe opening around giving automation its own settings/permissions; clarify when runs execute as a cloud agent vs the calling user (drop Warp app /cloud-agent bullet, which always runs as the user); convert endpoints HTML table to Markdown; remove the Team-scoped caller-requirement bullet
- self-hosting (managed-direct/docker/kubernetes, quickstart, reference): note the agent API key can be bound to any cloud agent and doesn't restrict which agents run on the worker
- unmanaged.mdx: 'agents' -> 'runs' are automatically team-scoped
Co-Authored-By: Oz <oz-agent@warp.dev>
* Update src/content/docs/reference/cli/api-keys.mdx
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
* docs: terminology + description cleanup from audit pass
- bring-your-own-llm.mdx: 'agent identity' -> 'cloud agent' (term carried in from main)
- agents.mdx: reframe frontmatter description to match the reworked opening (own settings/permissions vs acting as a user)
Co-Authored-By: Oz <oz-agent@warp.dev>
* docs: keep original cloud agents page description
Revert the frontmatter description change from the audit pass per preference; the reworked body opening is unchanged.
Co-Authored-By: Oz <oz-agent@warp.dev>
---------
Co-authored-by: Oz <oz-agent@warp.dev>
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
deploy-botorpr-reviewerthat your team can share. Runs inherit the agent's secrets and skills, and the Oz dashboard attributes them to that bot.Major rewrites
agent-platform/cloud-agents/agents.mdxagent identity/agent identitiesswapped tocloud agent/cloud agents(or justagentwhen context is unambiguous).Default Service Accountproper-noun dropped from concept paragraphs; "team default" used generically.reference/cli/api-keys.mdxPrincipals: 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 keyssection replaced withCloud agents power agent API keys— 1–2 sentences plus thedeploy-bot/pr-reviewerexamples.The Default Service Accountsection 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 authorizationreframed around "the cloud agent the key is bound to".Best practicesnow 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 theDefault Service Accountparentheticals and usecloud agentconsistently.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 likepr-reviewer."self-hosting/{quickstart,managed-docker,managed-kubernetes,managed-direct,unmanaged}.mdx— Drop the explicitDefault Service Accountname 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, andcli/index.mdxstill useagent identitybut weren't touched by this PR. Aligning them tocloud agentbelongs in a follow-up sweep so this PR stays scoped to what it originally changed.Validation
style_lint --changedshows 9 remaining warnings, all confirmed false positives (one fewer than before sinceThe Default Service Accountheader is gone).agent identity/agent identities/Default Service Accountremains in any file this PR touches.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:
This PR was generated with Oz.