docs: cover Personal / Team / Agent API key types#143
Open
hongyi-chen wants to merge 10 commits into
Open
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?
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
1 participant
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.