From 6a3aa18e53df7cd7cda2f3628e4c96822a428b89 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 26 May 2026 19:17:26 +0000 Subject: [PATCH 01/12] 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 --- .../integrations/github-actions.mdx | 2 +- .../quickstart-github-actions.mdx | 2 +- .../self-hosting/managed-direct.mdx | 2 +- .../self-hosting/managed-docker.mdx | 2 +- .../self-hosting/managed-kubernetes.mdx | 2 +- .../cloud-agents/self-hosting/quickstart.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 2 +- .../docs/reference/api-and-sdk/quickstart.mdx | 2 +- src/content/docs/reference/cli/api-keys.mdx | 81 ++++++++++++------- src/content/docs/reference/cli/quickstart.mdx | 2 +- 10 files changed, 60 insertions(+), 39 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 9bf7f2d7..a0247150 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -41,7 +41,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/#generating-api-keys) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp +* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Personal, team, and agent keys all work; see [API keys](/reference/cli/api-keys/) for the differences and when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx index 4d2ebc38..6cd81fe0 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx @@ -13,7 +13,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - In the Warp app, click your profile photo, then go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create one. Use a personal key if the agent needs to write to your repo. See [API Keys](/reference/cli/api-keys/) for details. +* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. Personal, team, and agent keys all work; use a personal key if the agent needs to write to your repo as you, or a team or agent key with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for headless workflows. See [API Keys](/reference/cli/api-keys/) for details. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx index 2fc2d350..060007c8 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx @@ -39,7 +39,7 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx index fb29b4f1..9c26f652 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx @@ -26,7 +26,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx index 278c424d..b056b2b7 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx @@ -38,7 +38,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx index 4eade66b..9a72422f 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx @@ -19,7 +19,7 @@ This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/ * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **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. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index 84d725d2..2105210f 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -33,7 +33,7 @@ No Docker, no worker daemon, no environment required — just the Oz CLI on any ### Prerequisites * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create a team-scoped API key in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for details. +* **A Warp API key** — For automation, create a team or agent API key in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). See [API Keys](/reference/cli/api-keys/) for details on each type. ### 1. Authenticate diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index f3472053..7985bbcb 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -17,7 +17,7 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe ## Prerequisites -* **A Warp API key** - In the Warp app, click your profile photo, then go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a key and copy the raw value. See [API Keys](/reference/cli/api-keys/) for step-by-step instructions. +* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys**, then copy the raw value. Personal, team, and agent keys all authenticate API requests — see [API Keys](/reference/cli/api-keys/) for step-by-step instructions and when to pick each type. * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) first. --- diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index c9207226..0b73bd4d 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -8,29 +8,44 @@ sidebar: API keys let the Oz CLI and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. -## Creating API keys +## API key types -You can create an API key from your settings in Warp: +Warp supports three types of API keys, each with different billing and identity behavior: -1. Click your profile photo in the top-right corner, then click **Settings**. -2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. -3. In the API Keys section, click **+ Create API Key**. -4. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). -5. Select the key type: - * `Personal` - Tied to your individual Warp account - * `Team` - Tied to your team, not any individual user +* **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 and execute under your team's default [agent identity](/agent-platform/cloud-agents/agents/). 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 API keys** - Cloud agent runs execute as a specific [agent identity](/agent-platform/cloud-agents/agents/) you choose at key creation time. Agent keys are a superset of team keys: every team starts with a built-in `Default Service Account` agent identity, and an Agent key bound to that identity behaves the same as a team API key (same billing waterfall, same team GitHub App behavior). Create additional agent identities — `ci-runner`, `nightly-jobs`, `on-call` — when you want runs from distinct workflows to be filterable and auditable as that bot in run history. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model. -:::note -When an agent needs to make code changes (e.g., opening pull requests, pushing branches, or writing to a repository), you have two options: - -* Use a **personal API key** to authenticate as you. The agent runs with your GitHub permissions, and code changes are attributed to your GitHub account. -* Use a **team API key** with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured. The agent authenticates with the Oz by Warp GitHub App, and code changes are not attributed to any individual user. -::: +Team and Agent 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/). :::note -Team keys without GitHub App authorization are the right fit for automated workflows that don't require writing to GitHub, such as analysis, monitoring, or triage. +**Migrating from a Team key to an Agent key?** No change is required. An Agent API key bound to the `Default Service Account` is functionally identical to a Team API key — same downstream billing, same GitHub App resolution, same headless-run behavior. The split into Personal/Team/Agent is a labeling change in the UI; existing Team keys continue to work and existing prerequisites that say "create a team-scoped API key" can be satisfied by either option. ::: +## Creating API keys + +You can create an API key in either the [Oz web app](https://oz.warp.dev/settings) or the Warp desktop app. The two surfaces produce keys that authenticate the CLI and SDK identically. + +### From the Oz web app (recommended) + +1. Open the Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings). +2. In the API Keys section, click **New API key**. +3. Choose the key type: + * **Personal** - Tied to your individual Warp account. + * **Agent** - Tied to a specific [agent identity](/agent-platform/cloud-agents/agents/) on your team. The dropdown lists every available identity, including the built-in `Default Service Account`. Use the default identity when you want behavior identical to a traditional team key; pick a named identity for workflow-scoped attribution. +4. Enter a name and choose an expiration (1 day, 30 days, 90 days, or never). +5. Click **Create key**. +6. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** + +### From the Warp desktop app + +1. In the Warp app, click your profile photo in the top-right corner, then click **Settings**. +2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. +3. In the API Keys section, click **+ Create API Key**. +4. Choose the key type: + * **Personal** - Tied to your individual Warp account. + * **Team** - Tied to your team's default agent identity (`Default Service Account`). Equivalent to creating an Agent key bound to the default identity from the Oz web app. +5. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). 6. Click **Create key**. 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** @@ -39,14 +54,20 @@ Team keys without GitHub App authorization are the right fit for automated workf
API key management interface in Warp settings.
-## Personal vs team API keys +:::note +To create or manage **named agent identities** (anything beyond the default), use the Oz web app at [oz.warp.dev/agents](https://oz.warp.dev/agents) or the [`oz agent`](/reference/api-and-sdk/) REST endpoints. The Warp desktop app's API key dialog binds team keys to the default identity automatically and does not expose the named-agent picker. +::: -Warp supports two types of API keys, each with different billing and identity behavior: +:::note +When an agent needs to make code changes (e.g., opening pull requests, pushing branches, or writing to a repository), you have two options: -* **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. +* Use a **personal API key** to authenticate as you. The agent runs with your GitHub permissions, and code changes are attributed to your GitHub account. +* Use a **team or agent API key** with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured. The agent authenticates with the Oz by Warp GitHub App, and code changes are not attributed to any individual user. +::: -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/). +:::note +Team and agent keys without GitHub App authorization are the right fit for automated workflows that don't require writing to GitHub, such as analysis, monitoring, or triage. +::: ## Authenticating with API keys @@ -71,30 +92,30 @@ API keys start with the prefix `wk-`. If your key doesn't have this prefix, it m ## Managing API keys -The API Keys section in **Settings** > **Cloud platform** > **Oz Cloud API Keys** displays all your active keys with the following information: +The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the Warp app's **Settings** > **Cloud platform** > **Oz Cloud API Keys** both display your active keys with the following information: * **Name** - The name you assigned when creating the key * **Key** - A masked suffix (`wk-**xxxx`) to help identify the key -* **Scope** - Whether the key is Personal or Team +* **Scope** - Whether the key is Personal, Team, or Agent. Agent keys also show which [agent identity](/agent-platform/cloud-agents/agents/) the key is bound to. * **Created** - When the key was created * **Last used** - When the key was last used for authentication * **Expires at** - The key's expiration date, or "Never" if it doesn't expire ### Deleting API keys -To delete an API key: - -1. Go to **Settings** > **Cloud platform** > **Oz Cloud API Keys**. -2. Find the key you want to delete in the API Keys list. -3. Click the delete icon next to the key. +To delete an API key, find it in the list and click the delete icon next to the key in either surface. Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access. +:::caution +Deleting a named [agent identity](/agent-platform/cloud-agents/agents/) atomically deletes every Agent API key bound to that identity. To rotate the identity instead of removing it, generate a new key first, swap your automation over, and then delete the old key. +::: + ## Best practices * **Use environment variables** - Avoid passing API keys directly in commands where they may be logged or visible in shell history. * **Set appropriate expiration** - Use shorter expiration times for development and testing; consider longer durations for stable production workflows. -* **Use team keys for automation** - For CI/CD and scheduled tasks, team keys provide cleaner billing attribution and don't depend on any individual user's account. -* **Use personal keys or configure team GitHub authorization when agents need to write to GitHub** - Personal keys authenticate as you; team keys can also write to GitHub when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured via the Admin Panel. +* **Use team or agent keys for automation** - For CI/CD and scheduled tasks, team and agent keys provide cleaner billing attribution and don't depend on any individual user's account. Pick a named agent identity when you want runs from distinct workflows to be filterable in the dashboard. +* **Use personal keys or configure team GitHub authorization when agents need to write to GitHub** - Personal keys authenticate as you; team and agent keys can also write to GitHub when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured via the Admin Panel. * **Rotate keys periodically** - Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. * **Store securely** - Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. diff --git a/src/content/docs/reference/cli/quickstart.mdx b/src/content/docs/reference/cli/quickstart.mdx index de2a145c..80ebf0c0 100644 --- a/src/content/docs/reference/cli/quickstart.mdx +++ b/src/content/docs/reference/cli/quickstart.mdx @@ -39,7 +39,7 @@ Interactive login works on both **local** and **remote** machines, and does not export WARP_API_KEY="wk-..." ``` -In the Warp app, create an API key in **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. team keys and security best practices. +Create an API key in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for guidance on personal, team, and agent keys, and on security best practices. ::: ## 3. Run an agent From f7a0ab2bc3741ff426492c692e21e90c9427be1a Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 26 May 2026 19:41:30 +0000 Subject: [PATCH 02/12] Broaden API key wording across billing, GitHub auth, and error docs 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 --- .../agent-platform/cloud-agents/agents.mdx | 8 ++++---- .../cloud-agents/environments.mdx | 2 +- .../cloud-agents/quickstart.mdx | 2 +- .../cloud-agents/self-hosting/reference.mdx | 2 +- .../team-access-billing-and-identity.mdx | 20 +++++++++---------- .../support-and-resources/billing.mdx | 2 +- .../team-management/admin-panel.mdx | 4 ++-- .../external-authentication-required.mdx | 2 +- .../errors/insufficient-credits.mdx | 12 +++++------ .../docs/reference/cli/integration-setup.mdx | 6 +++--- .../plans-and-billing/add-on-credits.mdx | 2 +- .../plans-and-billing/credits.mdx | 2 +- .../plans-and-billing/pricing-faqs.mdx | 4 ++-- 13 files changed, 34 insertions(+), 34 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index c22f7c20..7027718f 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -18,7 +18,7 @@ Agent identities are useful when you want to: ## How agent identities work -Each team has one default agent identity. Headless runs (such as team API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. +Each team has one default agent identity, called **Default Service Account**. Headless runs (such as team or agent API key runs that don't specify an identity) execute under this default — a Team API key created in the Warp desktop app and an Agent API key bound to the `Default Service Account` in the Oz web app behave identically. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. You can attach the following configuration to an agent identity: @@ -68,9 +68,9 @@ A few constraints apply across every endpoint: ## API keys bound to an agent identity -A team API key can be bound to a specific agent identity at creation time. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key. +An Agent API key is bound to a specific agent identity at creation time — the Oz web app's key dialog calls this the **Agent** key type. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key. -To create a key bound to an agent identity, choose the identity when creating the team API key. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys. +To create a key bound to a specific identity, choose the identity in the Oz web app's New API key dialog. Team API keys created in the Warp desktop app are equivalent to Agent API keys bound to the `Default Service Account`. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between personal, team, and agent keys. Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself. @@ -81,7 +81,7 @@ There are two ways to run a cloud agent as a specific agent identity: * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. -When neither path is used, headless runs (team API key runs without an identity) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. +When neither path is used, headless runs (team API key runs, or Agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. ## Where agent identities appear in the product diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx index ee398826..bdede06a 100644 --- a/src/content/docs/agent-platform/cloud-agents/environments.mdx +++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx @@ -133,7 +133,7 @@ You can create and configure environments with Warp’s guided setup, or through Make sure you have: * One or more GitHub repositories that the agent should clone and work in. -* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using team API keys, configure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. +* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using a team or agent API key, configure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. * A publicly-accessible Docker image that can build and run your code. Official images like [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), or [rust](https://hub.docker.com/_/rust) work for many projects. You can also use one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). :::caution diff --git a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx index 8e7b0d5c..85772162 100644 --- a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx @@ -154,7 +154,7 @@ Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatical Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images. **Agent can't access repos**\ -Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. +Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using a team or agent API key, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. **Not enough credits to run cloud agents**\ Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx index 3764033a..a97ecf99 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx @@ -20,7 +20,7 @@ The following flags are available when starting the worker. ### Required * `--worker-id` — A string identifying this worker. This is the value you pass to `--host` when routing tasks. Choose something meaningful for your team (e.g., `prod-runner-1` or `ci-worker`). Multiple workers can share the same ID for load balancing. -* `--api-key` or `WARP_API_KEY` env var — Your team API key for authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. +* `--api-key` or `WARP_API_KEY` env var — Your team or agent API key for authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. ### Optional diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index f000e7ee..3f693456 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -82,7 +82,7 @@ Your team must meet the following requirements to run integrations: When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to: * **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. * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms. If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. @@ -108,13 +108,13 @@ This ensures runs are scoped to what the user is allowed to see and modify, and By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Oz by Warp** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. -This is useful for fully automated workflows that use a [team API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. +This is useful for fully automated workflows that use a team or [agent API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works -When an agent task is initiated with a team API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. +When an agent task is initiated with a team or agent API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. -The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what team API key runs can access. +The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what team and agent API key runs can access. ### Setting up team GitHub authorization @@ -140,11 +140,11 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use a team API key.** Tasks initiated with a team API key now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. +3. **Use a team or agent API key.** Tasks initiated with a team API key (Warp desktop app) or an Agent API key bound to any agent identity (Oz web app) now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. ### How this relates to environments -An [environment](/agent-platform/cloud-agents/environments/) is a template for a cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by team API key runs, and each will authenticate to GitHub independently. +An [environment](/agent-platform/cloud-agents/environments/) is a template for a cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by team and agent API key runs, and each will authenticate to GitHub independently. The environment configuration and the **Enabled GitHub Orgs** setting in the Admin Panel serve different purposes: @@ -156,9 +156,9 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm Team GitHub authorization is complementary to the existing personal token flow: * **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. -Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with a team API key. +Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with a team or agent API key. :::caution GitHub App installation tokens are scoped to a single GitHub organization at a time. If your team works across repos in multiple GitHub organizations, the agent can only use the installation token for the organization enabled in the Admin Panel. Repos in other organizations require user-triggered runs with a personal API key. @@ -219,7 +219,7 @@ How credits are consumed depends on how the agent run is triggered and authentic * On Build, Max, and Business plans, credits are consumed starting with any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) allocated to the user, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user. * On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms. -**Team API key and scheduled cloud agent runs** (fully automated or headless workflows): +**Team or agent API key and scheduled cloud agent runs** (fully automated or headless workflows): * 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. With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. @@ -244,7 +244,7 @@ All triggers and instructions used by cloud agents are defined and controlled by Because triggers and instructions are configured by your team, the credits consumed when an agent runs are billed according to the model above: -* **Build, Max, Business** - User-triggered runs draw from the triggering user's pools (plan-included credits, then their add-on credits). Team API key and scheduled cloud agent runs are billed to the team owner (the owner's plan-included credits, then the owner's add-on credits, subject to the team-wide spend cap when auto-reload is on). +* **Build, Max, Business** - User-triggered runs draw from the triggering user's pools (plan-included credits, then their add-on credits). Team or agent API key runs and scheduled cloud agent runs are billed to the team owner (the owner's plan-included credits, then the owner's add-on credits, subject to the team-wide spend cap when auto-reload is on). * **Enterprise** - All runs draw from the team-scoped credit pool, per your Enterprise contract terms. It's the team's responsibility to manage triggers, confirm they behave as intended, and monitor usage. Reviewing triggers, prompts, and agent behavior periodically helps ensure that credit usage aligns with expectations. diff --git a/src/content/docs/enterprise/support-and-resources/billing.mdx b/src/content/docs/enterprise/support-and-resources/billing.mdx index 46638e3f..4b08155d 100644 --- a/src/content/docs/enterprise/support-and-resources/billing.mdx +++ b/src/content/docs/enterprise/support-and-resources/billing.mdx @@ -37,7 +37,7 @@ Cloud agents consume AI credits for inference, compute credits for the sandbox t On Enterprise plans, local and cloud agent usage both draw from the same team credit pool across all three credit types (AI credits, compute credits, and platform credits). The credit type a run consumes depends on what infrastructure it uses, not on whether it's local or cloud. -For team API key runs (e.g., CI/CD pipelines, scheduled tasks), credits also draw from the team's shared pool since these runs are not tied to any individual user. +For team and agent API key runs (e.g., CI/CD pipelines, scheduled tasks), credits also draw from the team's shared pool since these runs are not tied to any individual user. For more details, see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index 56bd4b25..4147e14d 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -252,7 +252,7 @@ Configure cloud agent settings for your team, including GitHub authorization for **Enabled GitHub Orgs** -The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations, enabling cloud agents initiated with a [team API key](/reference/cli/api-keys/) to clone repositories and open pull requests using the Oz by Warp GitHub App. +The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations, enabling cloud agents initiated with a team or [agent API key](/reference/cli/api-keys/) to clone repositories and open pull requests using the Oz by Warp GitHub App. To configure: @@ -268,7 +268,7 @@ To configure: The organizations and repository access shown here reflect the Oz by Warp GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub. :::note -This setting controls GitHub access for team API key runs only. Runs triggered by individual users (via personal API key, Slack, or Linear) continue to use that user's personal GitHub token. For more details, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). +This setting controls GitHub access for team and agent API key runs only. Runs triggered by individual users (via personal API key, Slack, or Linear) continue to use that user's personal GitHub token. For more details, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). ::: ## Multi-admin functionality diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index 72433c1e..d28d7969 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -101,7 +101,7 @@ This error includes extra fields beyond the standard response format: 2. Ensure the app has access to all repositories listed in `inaccessible_repos`. 3. Retry the task. -If you are using a **team API key** bound to an [agent identity](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. +If you are using a **team or agent API key** bound to an [agent identity](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. ### Account matching failed diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx index f7133cbf..45e9fae2 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx @@ -2,8 +2,8 @@ title: insufficient_credits description: >- The principal billed for the run has no remaining credits. Top up the - right pool — the triggering user's, or the team owner's for team API - key and scheduled runs — to continue. + right pool — the triggering user's, or the team owner's for team or + agent API key and scheduled runs — to continue. --- The `insufficient_credits` error occurs when the principal billed for a cloud agent run has no remaining credits to charge against. @@ -11,7 +11,7 @@ The `insufficient_credits` error occurs when the principal billed for a cloud ag On self-serve plans (Build, Max, Business), the billed principal depends on how the run was triggered: * **User-triggered runs** draw from the triggering user's pool: plan-included credits first, then their user-scoped add-on credits. -* **Team API key and scheduled runs** draw from the team owner's pool: the owner's plan-included credits first, then the owner's add-on credits. +* **Team and agent API key, and scheduled runs** draw from the team owner's pool: the owner's plan-included credits first, then the owner's add-on credits. When both pools are depleted and [auto-reload](/support-and-community/plans-and-billing/add-on-credits/) is off, new runs return this error. On Enterprise plans, runs draw from the team-scoped credit pool per your contract — contact your account manager when the pool is exhausted. @@ -30,7 +30,7 @@ When both pools are depleted and [auto-reload](/support-and-community/plans-and- This error is returned when: * A user-triggered run runs out of the user's plan-included credits and their user-scoped add-on credits. -* A team API key or scheduled run runs out of the team owner's plan-included credits and the owner's add-on credits. +* A team or agent API key, or scheduled run, runs out of the team owner's plan-included credits and the owner's add-on credits. * Auto-reload is off, or auto-reload is on but the team-wide monthly spend cap has been reached. For the full waterfall, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. @@ -61,7 +61,7 @@ The fix depends on which principal was billed. 2. Alternatively, enable auto-reload, subject to your team's monthly spend cap. 3. Retry the failed operation. -**For team API key or scheduled runs (the team owner's pool was exhausted):** +**For team or agent API key, or scheduled runs (the team owner's pool was exhausted):** 1. The team owner tops up their pool: purchase add-on credits or wait for the monthly refresh. 2. If auto-reload is on but the team-wide spend cap was reached, an admin can raise the cap in **Settings** > **Billing and usage**. @@ -73,7 +73,7 @@ If you are not a team admin or the team owner, contact them to top up the right ## Related -* [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Credit billing for individual and team API key runs. +* [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Credit billing for individual, team, and agent API key runs. * [Add-on credits](/support-and-community/plans-and-billing/add-on-credits/) — Purchase additional credits and configure auto-reload. * [Platform credits](/support-and-community/plans-and-billing/platform-credits/) — The third credit bucket alongside AI credits and compute credits. * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Billing and plan requirements for cloud agents. diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index 97db4c3a..2bc93a53 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -178,14 +178,14 @@ You typically only need to handle this once per team, unless your repo access ch #### Team-level GitHub authorization -For automated workflows that use a [team API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Oz by Warp GitHub App instead of an individual's personal token. +For automated workflows that use a team or [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Oz by Warp GitHub App instead of an individual's personal token. -This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with a team API key can clone repos and open pull requests using the GitHub App installation token. +This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with a team or agent API key can clone repos and open pull requests using the GitHub App installation token. For full setup instructions, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). :::note -**Using API keys:** Personal API keys authenticate as you, so the agent runs with your GitHub permissions and code changes are attributed to your account. Team API keys with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured use the GitHub App token instead. +**Using API keys:** Personal API keys authenticate as you, so the agent runs with your GitHub permissions and code changes are attributed to your account. Team and agent API keys with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured use the GitHub App token instead. ::: --- diff --git a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx index 4fa79bd4..de43d01d 100644 --- a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx @@ -81,7 +81,7 @@ Team admins manage add-on credit settings for the team in **Settings** > **Billi * **Auto-reload** — When enabled, the admin selects an add-on credit denomination for the team. Warp automatically purchases that denomination for any user whose add-on credit balance drops below 100 credits, subject to the team-wide spend cap. While auto-reload is on, individual users cannot purchase add-on credits manually. * **Manual purchases** — When auto-reload is off, eligible team members can purchase add-on credits for themselves, as long as the team stays below the team-wide spend cap. -For how cloud agent runs that aren't initiated by a specific team member (scheduled runs, team API key runs) are billed, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. +For how cloud agent runs that aren't initiated by a specific team member (scheduled runs, team or agent API key runs) are billed, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. ### Plan changes and cancellations diff --git a/src/content/docs/support-and-community/plans-and-billing/credits.mdx b/src/content/docs/support-and-community/plans-and-billing/credits.mdx index 4819d112..178e7bb1 100644 --- a/src/content/docs/support-and-community/plans-and-billing/credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/credits.mdx @@ -161,6 +161,6 @@ For a full breakdown of how platform credits work, see [platform credits](/suppo ### Cloud agent runs on team plans -Cloud agent runs that aren't initiated by a specific team member — for example, scheduled runs or runs triggered through a team API key — follow plan-specific billing rules. On self-serve plans (Build, Max, Business), these runs are billed to the team owner: the owner's plan-included credits first, then their 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 spend cap. On Enterprise plans, these runs draw from the team-scoped credit pool per your contract. +Cloud agent runs that aren't initiated by a specific team member — for example, scheduled runs or runs triggered through a team or agent API key — follow plan-specific billing rules. On self-serve plans (Build, Max, Business), these runs are billed to the team owner: the owner's plan-included credits first, then their 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 spend cap. On Enterprise plans, these runs draw from the team-scoped credit pool per your contract. For the full waterfall, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. diff --git a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx index 5aed7023..b48171ee 100644 --- a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx @@ -189,10 +189,10 @@ Auto-reload can be enabled, paused, or reconfigured at any time in **Settings** ### 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 a team or agent API key. On self-serve plans (Build, Max, Business), these runs are billed to the **team owner**. :::caution -Team owners: scheduled runs and runs triggered through a team API key draw from your personal credit pool. If auto-reload is enabled on your account, automated jobs can consume your add-on credits and count toward your spend cap. Review your auto-reload settings and team-wide spend cap in **Settings** > **Billing and usage** before relying on scheduled or API-key-triggered cloud agents. +Team owners: scheduled runs and runs triggered through a team or agent API key draw from your personal credit pool. If auto-reload is enabled on your account, automated jobs can consume your add-on credits and count toward your spend cap. Review your auto-reload settings and team-wide spend cap in **Settings** > **Billing and usage** before relying on scheduled or API-key-triggered cloud agents. ::: The waterfall on the owner's account is: From 0baf997f865d5fd4d76ecd2f0e3e5c8864c6bedf Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 26 May 2026 22:47:11 +0000 Subject: [PATCH 03/12] Final pass: normalize key-type casing, remove redundant Enterprise sentence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../docs/agent-platform/cloud-agents/agents.mdx | 8 ++++---- .../cloud-agents/self-hosting/managed-direct.mdx | 2 +- .../cloud-agents/self-hosting/managed-docker.mdx | 2 +- .../self-hosting/managed-kubernetes.mdx | 2 +- .../cloud-agents/self-hosting/quickstart.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 2 +- .../team-access-billing-and-identity.mdx | 6 +++--- src/content/docs/reference/cli/api-keys.mdx | 16 ++++++++-------- 8 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 7027718f..3ac92e69 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -18,7 +18,7 @@ Agent identities are useful when you want to: ## How agent identities work -Each team has one default agent identity, called **Default Service Account**. Headless runs (such as team or agent API key runs that don't specify an identity) execute under this default — a Team API key created in the Warp desktop app and an Agent API key bound to the `Default Service Account` in the Oz web app behave identically. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. +Each team has one default agent identity, called `Default Service Account`. Headless runs (such as team or agent API key runs that don't specify an identity) execute under this default — a team API key created in the Warp desktop app and an agent API key bound to the `Default Service Account` in the Oz web app behave identically. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. You can attach the following configuration to an agent identity: @@ -68,9 +68,9 @@ A few constraints apply across every endpoint: ## API keys bound to an agent identity -An Agent API key is bound to a specific agent identity at creation time — the Oz web app's key dialog calls this the **Agent** key type. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key. +An agent API key is bound to a specific agent identity at creation time — the Oz web app's key dialog calls this the **Agent** key type. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key. -To create a key bound to a specific identity, choose the identity in the Oz web app's New API key dialog. Team API keys created in the Warp desktop app are equivalent to Agent API keys bound to the `Default Service Account`. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between personal, team, and agent keys. +To create a key bound to a specific identity, choose the identity in the Oz web app's New API key dialog. Team API keys created in the Warp desktop app are equivalent to agent API keys bound to the `Default Service Account`. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between personal, team, and agent keys. Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself. @@ -81,7 +81,7 @@ There are two ways to run a cloud agent as a specific agent identity: * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. -When neither path is used, headless runs (team API key runs, or Agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. +When neither path is used, headless runs (team API key runs, or agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. ## Where agent identities appear in the product diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx index 060007c8..0b3c3025 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx @@ -39,7 +39,7 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx index 9c26f652..e2828e19 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx @@ -26,7 +26,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx index b056b2b7..dc40d0fa 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx @@ -38,7 +38,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx index 9a72422f..16e11c8a 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx @@ -19,7 +19,7 @@ This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/ * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index 2105210f..f7af8681 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -33,7 +33,7 @@ No Docker, no worker daemon, no environment required — just the Oz CLI on any ### Prerequisites * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create a team or agent API key in the [Oz web app](https://oz.warp.dev/settings) (`Agent` type bound to the `Default Service Account`) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys** (`Team` type). See [API Keys](/reference/cli/api-keys/) for details on each type. +* **A Warp API key** — For automation, create a team or agent API key in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). See [API Keys](/reference/cli/api-keys/) for details on each type. ### 1. Authenticate diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index 3f693456..437be921 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -82,7 +82,7 @@ Your team must meet the following requirements to run integrations: When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to: * **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 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. * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms. If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. @@ -140,7 +140,7 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use a team or agent API key.** Tasks initiated with a team API key (Warp desktop app) or an Agent API key bound to any agent identity (Oz web app) now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. +3. **Use a team or agent API key.** Tasks initiated with a team API key (Warp desktop app) or an agent API key bound to any agent identity (Oz web app) now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. ### How this relates to environments @@ -156,7 +156,7 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm Team GitHub authorization is complementary to the existing personal token flow: * **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 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 agent identity — or, for team keys created in the Warp desktop app, the team's `Default Service Account` — rather than any individual user. Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with a team or agent API key. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 0b73bd4d..26625ff0 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -14,12 +14,12 @@ Warp supports three types of API keys, each with different billing and identity * **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 and execute under your team's default [agent identity](/agent-platform/cloud-agents/agents/). 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 API keys** - Cloud agent runs execute as a specific [agent identity](/agent-platform/cloud-agents/agents/) you choose at key creation time. Agent keys are a superset of team keys: every team starts with a built-in `Default Service Account` agent identity, and an Agent key bound to that identity behaves the same as a team API key (same billing waterfall, same team GitHub App behavior). Create additional agent identities — `ci-runner`, `nightly-jobs`, `on-call` — when you want runs from distinct workflows to be filterable and auditable as that bot in run history. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model. +* **Agent API keys** - Cloud agent runs execute as a specific [agent identity](/agent-platform/cloud-agents/agents/) you choose at key creation time. Agent keys are a superset of team keys: every team starts with a built-in `Default Service Account` agent identity, and an agent key bound to that identity behaves the same as a team API key (same billing waterfall, same team GitHub App behavior). Create additional agent identities — `ci-runner`, `nightly-jobs`, `on-call` — when you want runs from distinct workflows to be filterable and auditable as that bot in run history. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model. -Team and Agent 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/). +Team and agent 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/). :::note -**Migrating from a Team key to an Agent key?** No change is required. An Agent API key bound to the `Default Service Account` is functionally identical to a Team API key — same downstream billing, same GitHub App resolution, same headless-run behavior. The split into Personal/Team/Agent is a labeling change in the UI; existing Team keys continue to work and existing prerequisites that say "create a team-scoped API key" can be satisfied by either option. +**Migrating from a team key to an agent key?** No change is required. An agent API key bound to the `Default Service Account` is functionally identical to a team API key — same downstream billing, same GitHub App resolution, same headless-run behavior. The split into `Personal` / `Team` / `Agent` is a labeling change in the UI; existing team keys continue to work and existing prerequisites that say "create a team-scoped API key" can be satisfied by either option. ::: ## Creating API keys @@ -32,7 +32,7 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting 2. In the API Keys section, click **New API key**. 3. Choose the key type: * **Personal** - Tied to your individual Warp account. - * **Agent** - Tied to a specific [agent identity](/agent-platform/cloud-agents/agents/) on your team. The dropdown lists every available identity, including the built-in `Default Service Account`. Use the default identity when you want behavior identical to a traditional team key; pick a named identity for workflow-scoped attribution. + * **Agent** - Tied to a specific [agent identity](/agent-platform/cloud-agents/agents/) on your team. The dropdown lists every available identity, including the built-in `Default Service Account`. Pick the default identity when you want behavior identical to a traditional team key, or a named identity for workflow-scoped attribution. 4. Enter a name and choose an expiration (1 day, 30 days, 90 days, or never). 5. Click **Create key**. 6. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** @@ -44,7 +44,7 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting 3. In the API Keys section, click **+ Create API Key**. 4. Choose the key type: * **Personal** - Tied to your individual Warp account. - * **Team** - Tied to your team's default agent identity (`Default Service Account`). Equivalent to creating an Agent key bound to the default identity from the Oz web app. + * **Team** - Tied to your team's default agent identity (`Default Service Account`). Equivalent to creating an agent key bound to the default identity from the Oz web app. 5. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). 6. Click **Create key**. 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** @@ -96,19 +96,19 @@ The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the W * **Name** - The name you assigned when creating the key * **Key** - A masked suffix (`wk-**xxxx`) to help identify the key -* **Scope** - Whether the key is Personal, Team, or Agent. Agent keys also show which [agent identity](/agent-platform/cloud-agents/agents/) the key is bound to. +* **Scope** - Whether the key is **Personal**, **Team**, or **Agent**. Agent keys also show which [agent identity](/agent-platform/cloud-agents/agents/) the key is bound to. * **Created** - When the key was created * **Last used** - When the key was last used for authentication * **Expires at** - The key's expiration date, or "Never" if it doesn't expire ### Deleting API keys -To delete an API key, find it in the list and click the delete icon next to the key in either surface. +To delete an API key, find it in either the Oz web app or the Warp desktop app's API Keys list and click the delete icon next to the key. Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access. :::caution -Deleting a named [agent identity](/agent-platform/cloud-agents/agents/) atomically deletes every Agent API key bound to that identity. To rotate the identity instead of removing it, generate a new key first, swap your automation over, and then delete the old key. +Deleting a named [agent identity](/agent-platform/cloud-agents/agents/) atomically deletes every agent API key bound to that identity. To rotate the identity instead of removing it, generate a new key first, swap your automation over, and then delete the old key. ::: ## Best practices From a435884cbc93d04b4117cce2add765134c1f6ad5 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 26 May 2026 23:00:20 +0000 Subject: [PATCH 04/12] 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 --- .../agent-platform/cloud-agents/agents.mdx | 6 ++-- .../cloud-agents/environments.mdx | 2 +- .../integrations/github-actions.mdx | 2 +- .../quickstart-github-actions.mdx | 2 +- .../cloud-agents/quickstart.mdx | 2 +- .../self-hosting/managed-direct.mdx | 4 +-- .../self-hosting/managed-docker.mdx | 6 ++-- .../self-hosting/managed-kubernetes.mdx | 4 +-- .../cloud-agents/self-hosting/quickstart.mdx | 6 ++-- .../cloud-agents/self-hosting/reference.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 6 ++-- .../team-access-billing-and-identity.mdx | 20 ++++++------ .../enterprise-features/analytics-api.mdx | 4 +-- .../support-and-resources/billing.mdx | 2 +- .../team-management/admin-panel.mdx | 4 +-- .../docs/reference/api-and-sdk/quickstart.mdx | 2 +- .../external-authentication-required.mdx | 2 +- .../errors/insufficient-credits.mdx | 12 +++---- src/content/docs/reference/cli/api-keys.mdx | 31 +++++++++---------- .../docs/reference/cli/integration-setup.mdx | 6 ++-- src/content/docs/reference/cli/quickstart.mdx | 2 +- .../plans-and-billing/add-on-credits.mdx | 2 +- .../plans-and-billing/credits.mdx | 2 +- .../plans-and-billing/pricing-faqs.mdx | 4 +-- 24 files changed, 66 insertions(+), 69 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 3ac92e69..9bcc3877 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -18,7 +18,7 @@ Agent identities are useful when you want to: ## How agent identities work -Each team has one default agent identity, called `Default Service Account`. Headless runs (such as team or agent API key runs that don't specify an identity) execute under this default — a team API key created in the Warp desktop app and an agent API key bound to the `Default Service Account` in the Oz web app behave identically. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. +Each team has one default agent identity, called `Default Service Account`. Headless runs (such as agent API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. You can attach the following configuration to an agent identity: @@ -70,7 +70,7 @@ A few constraints apply across every endpoint: An agent API key is bound to a specific agent identity at creation time — the Oz web app's key dialog calls this the **Agent** key type. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key. -To create a key bound to a specific identity, choose the identity in the Oz web app's New API key dialog. Team API keys created in the Warp desktop app are equivalent to agent API keys bound to the `Default Service Account`. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between personal, team, and agent keys. +To create a key bound to a specific identity, choose the identity in the Oz web app's New API key dialog. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between personal and agent keys, including the note on the legacy team-key label. Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself. @@ -81,7 +81,7 @@ There are two ways to run a cloud agent as a specific agent identity: * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. -When neither path is used, headless runs (team API key runs, or agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. +When neither path is used, headless runs (agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. ## Where agent identities appear in the product diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx index bdede06a..d3e2eb68 100644 --- a/src/content/docs/agent-platform/cloud-agents/environments.mdx +++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx @@ -133,7 +133,7 @@ You can create and configure environments with Warp’s guided setup, or through Make sure you have: * One or more GitHub repositories that the agent should clone and work in. -* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using a team or agent API key, configure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. +* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using an agent API key, configure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. * A publicly-accessible Docker image that can build and run your code. Official images like [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), or [rust](https://hub.docker.com/_/rust) work for many projects. You can also use one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). :::caution diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index a0247150..b4f7c4c2 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -41,7 +41,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Personal, team, and agent keys all work; see [API keys](/reference/cli/api-keys/) for the differences and when to pick each. +* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Personal and agent keys both work; see [API keys](/reference/cli/api-keys/) for the differences and when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx index 6cd81fe0..d492bf96 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx @@ -13,7 +13,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. Personal, team, and agent keys all work; use a personal key if the agent needs to write to your repo as you, or a team or agent key with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for headless workflows. See [API Keys](/reference/cli/api-keys/) for details. +* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. Personal and agent keys both work; use a personal key if the agent needs to write to your repo as you, or an agent key with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for headless workflows. See [API Keys](/reference/cli/api-keys/) for details, including the note on the legacy team-key label. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx index 85772162..3c56f3fa 100644 --- a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx @@ -154,7 +154,7 @@ Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatical Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images. **Agent can't access repos**\ -Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using a team or agent API key, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. +Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using an agent API key, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. **Not enough credits to run cloud agents**\ Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx index 0b3c3025..b8bb118a 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx @@ -39,7 +39,7 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. --- @@ -50,7 +50,7 @@ The Direct backend does not provide per-task container isolation. Each task runs Export the API key so the worker can authenticate to Oz: ```bash -export WARP_API_KEY="your_team_api_key" +export WARP_API_KEY="your_agent_api_key" ``` ### 2. Start the worker with the Direct backend diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx index e2828e19..f91e540d 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx @@ -26,7 +26,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. @@ -46,10 +46,10 @@ docker info ## Set your API key -Export your team API key so the worker can authenticate to Oz: +Export your agent API key so the worker can authenticate to Oz: ```bash -export WARP_API_KEY="your_team_api_key" +export WARP_API_KEY="your_agent_api_key" ``` ## Install and run the worker diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx index dc40d0fa..136d8a7a 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx @@ -38,7 +38,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. --- @@ -59,7 +59,7 @@ The chart does not create CRDs or cluster-scoped RBAC resources. ### 1. Set your API key and namespace ```bash -export WARP_API_KEY="your_team_api_key" +export WARP_API_KEY="your_agent_api_key" ``` Create the namespace if it doesn't exist: diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx index 16e11c8a..8435cefa 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx @@ -19,7 +19,7 @@ This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/ * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **A team or agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). The two options are equivalent for self-hosting. See [API Keys](/reference/cli/api-keys/) for details. +* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). --- @@ -30,10 +30,10 @@ _~10 minutes_ ### 1. Export your API key -Export the team API key so the worker container can authenticate to Oz automatically: +Export the agent API key so the worker container can authenticate to Oz automatically: ```bash -export WARP_API_KEY="your_team_api_key" +export WARP_API_KEY="your_agent_api_key" ``` ### 2. Start the worker diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx index a97ecf99..da496e85 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/reference.mdx @@ -20,7 +20,7 @@ The following flags are available when starting the worker. ### Required * `--worker-id` — A string identifying this worker. This is the value you pass to `--host` when routing tasks. Choose something meaningful for your team (e.g., `prod-runner-1` or `ci-worker`). Multiple workers can share the same ID for load balancing. -* `--api-key` or `WARP_API_KEY` env var — Your team or agent API key for authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. +* `--api-key` or `WARP_API_KEY` env var — Your agent API key for authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. ### Optional diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index f7af8681..538322f1 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -33,14 +33,14 @@ No Docker, no worker daemon, no environment required — just the Oz CLI on any ### Prerequisites * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create a team or agent API key in the [Oz web app](https://oz.warp.dev/settings) (**Agent** type bound to the `Default Service Account`) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys** (**Team** type). See [API Keys](/reference/cli/api-keys/) for details on each type. +* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings) (click **New API key**, pick **Agent**, bind it to the built-in `Default Service Account`). The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. ### 1. Authenticate Export your API key so the CLI can authenticate requests automatically: ```bash -export WARP_API_KEY="your_team_api_key" +export WARP_API_KEY="your_agent_api_key" ``` ### 2. Run an agent @@ -63,7 +63,7 @@ Use `--share` to control who can attach to the session and steer the agent: * `--share user@example.com` — Give a specific user read-only access. * `--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. --- diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index 437be921..467383db 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -82,7 +82,7 @@ Your team must meet the following requirements to run integrations: When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to: * **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 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. +* **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. * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms. If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. @@ -108,13 +108,13 @@ This ensures runs are scoped to what the user is allowed to see and modify, and By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Oz by Warp** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. -This is useful for fully automated workflows that use a team or [agent API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. +This is useful for fully automated workflows that use an [agent API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works -When an agent task is initiated with a team or agent API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. +When an agent task is initiated with an agent API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. -The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what team and agent API key runs can access. +The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what agent API key runs can access. ### Setting up team GitHub authorization @@ -140,11 +140,11 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use a team or agent API key.** Tasks initiated with a team API key (Warp desktop app) or an agent API key bound to any agent identity (Oz web app) now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. +3. **Use an agent API key.** Tasks initiated with an agent API key (or a legacy team API key created in the Warp desktop app, which is equivalent to an agent key bound to the `Default Service Account`) now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. ### How this relates to environments -An [environment](/agent-platform/cloud-agents/environments/) is a template for a cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by team and agent API key runs, and each will authenticate to GitHub independently. +An [environment](/agent-platform/cloud-agents/environments/) is a template for a cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by agent API key runs, and each will authenticate to GitHub independently. The environment configuration and the **Enabled GitHub Orgs** setting in the Admin Panel serve different purposes: @@ -156,9 +156,9 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm Team GitHub authorization is complementary to the existing personal token flow: * **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 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 team keys created in the Warp desktop app, the team's `Default Service Account` — rather than any individual user. +* **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 (the `Default Service Account` for legacy team keys) rather than any individual user. -Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with a team or agent API key. +Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with an agent API key. :::caution GitHub App installation tokens are scoped to a single GitHub organization at a time. If your team works across repos in multiple GitHub organizations, the agent can only use the installation token for the organization enabled in the Admin Panel. Repos in other organizations require user-triggered runs with a personal API key. @@ -219,7 +219,7 @@ How credits are consumed depends on how the agent run is triggered and authentic * On Build, Max, and Business plans, credits are consumed starting with any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) allocated to the user, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user. * On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms. -**Team or agent API key and scheduled cloud agent runs** (fully automated or headless workflows): +**Agent API key and scheduled cloud agent runs** (fully automated or headless workflows): * 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. With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. @@ -244,7 +244,7 @@ All triggers and instructions used by cloud agents are defined and controlled by Because triggers and instructions are configured by your team, the credits consumed when an agent runs are billed according to the model above: -* **Build, Max, Business** - User-triggered runs draw from the triggering user's pools (plan-included credits, then their add-on credits). Team or agent API key runs and scheduled cloud agent runs are billed to the team owner (the owner's plan-included credits, then the owner's add-on credits, subject to the team-wide spend cap when auto-reload is on). +* **Build, Max, Business** - User-triggered runs draw from the triggering user's pools (plan-included credits, then their add-on credits). Agent API key runs and scheduled cloud agent runs are billed to the team owner (the owner's plan-included credits, then the owner's add-on credits, subject to the team-wide spend cap when auto-reload is on). * **Enterprise** - All runs draw from the team-scoped credit pool, per your Enterprise contract terms. It's the team's responsibility to manage triggers, confirm they behave as intended, and monitor usage. Reviewing triggers, prompts, and agent behavior periodically helps ensure that credit usage aligns with expectations. diff --git a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx index 36688e05..8b6b6074 100644 --- a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx +++ b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx @@ -28,7 +28,7 @@ Before you can call the API, your team must satisfy all of the following: * **Enterprise plan** - The Analytics API is available to all enterprise teams during Early Access; no separate enrollment is required. * **Admin role on the team** - Calls are rejected unless the authenticated user has admin-level permissions on the enterprise team. See [Roles and permissions](/enterprise/team-management/roles-and-permissions/). -* **A personal Warp API key** - Authenticate requests with a key from **Settings** > **Cloud platform** > **Oz Cloud API Keys** in the Warp app. See [API Keys](/reference/cli/api-keys/) for step-by-step instructions. Team API keys are not accepted by these endpoints — only personal API keys belonging to a team admin work. +* **A personal Warp API key** - Authenticate requests with a key from **Settings** > **Cloud platform** > **Oz Cloud API Keys** in the Warp app. See [API Keys](/reference/cli/api-keys/) for step-by-step instructions. Agent API keys (including legacy team keys) are not accepted by these endpoints — only personal API keys belonging to a team admin work. * **Enterprise Usage Reporting toggle enabled** - In the Warp app, go to **Admin Panel** > **Privacy** and turn on **Enterprise Usage Reporting (Early Access)**. Until this toggle is on, no usage data is recorded for your team and the endpoints will return empty datasets even if every other prerequisite is met. :::caution @@ -296,7 +296,7 @@ Any authenticated user with admin-level permissions on an enterprise team. Calls ### What kind of API key works? -Only **personal** Warp API keys created by an admin from **Settings** > **Cloud platform** > **Oz Cloud API Keys**. Team API keys are explicitly rejected by these endpoints. See [API Keys](/reference/cli/api-keys/) for how to create one. +Only **personal** Warp API keys created by an admin from **Settings** > **Cloud platform** > **Oz Cloud API Keys**. Agent API keys (including legacy team keys) are explicitly rejected by these endpoints. See [API Keys](/reference/cli/api-keys/) for how to create one. ### Are these calls billed? diff --git a/src/content/docs/enterprise/support-and-resources/billing.mdx b/src/content/docs/enterprise/support-and-resources/billing.mdx index 4b08155d..e35ec87d 100644 --- a/src/content/docs/enterprise/support-and-resources/billing.mdx +++ b/src/content/docs/enterprise/support-and-resources/billing.mdx @@ -37,7 +37,7 @@ Cloud agents consume AI credits for inference, compute credits for the sandbox t On Enterprise plans, local and cloud agent usage both draw from the same team credit pool across all three credit types (AI credits, compute credits, and platform credits). The credit type a run consumes depends on what infrastructure it uses, not on whether it's local or cloud. -For team and agent API key runs (e.g., CI/CD pipelines, scheduled tasks), credits also draw from the team's shared pool since these runs are not tied to any individual user. +For agent API key runs (e.g., CI/CD pipelines, scheduled tasks), credits also draw from the team's shared pool since these runs are not tied to any individual user. For more details, see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index 4147e14d..4cbc7d3b 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -252,7 +252,7 @@ Configure cloud agent settings for your team, including GitHub authorization for **Enabled GitHub Orgs** -The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations, enabling cloud agents initiated with a team or [agent API key](/reference/cli/api-keys/) to clone repositories and open pull requests using the Oz by Warp GitHub App. +The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations, enabling cloud agents initiated with an [agent API key](/reference/cli/api-keys/) to clone repositories and open pull requests using the Oz by Warp GitHub App. To configure: @@ -268,7 +268,7 @@ To configure: The organizations and repository access shown here reflect the Oz by Warp GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub. :::note -This setting controls GitHub access for team and agent API key runs only. Runs triggered by individual users (via personal API key, Slack, or Linear) continue to use that user's personal GitHub token. For more details, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). +This setting controls GitHub access for agent API key runs only. Runs triggered by individual users (via personal API key, Slack, or Linear) continue to use that user's personal GitHub token. For more details, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). ::: ## Multi-admin functionality diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index 7985bbcb..5ef87d30 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -17,7 +17,7 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe ## Prerequisites -* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys**, then copy the raw value. Personal, team, and agent keys all authenticate API requests — see [API Keys](/reference/cli/api-keys/) for step-by-step instructions and when to pick each type. +* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys**, then copy the raw value. Personal and agent keys both authenticate API requests — see [API Keys](/reference/cli/api-keys/) for step-by-step instructions and when to pick each type. * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) first. --- diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index d28d7969..461e58dd 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -101,7 +101,7 @@ This error includes extra fields beyond the standard response format: 2. Ensure the app has access to all repositories listed in `inaccessible_repos`. 3. Retry the task. -If you are using a **team or agent API key** bound to an [agent identity](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. +If you are using an **agent API key** bound to an [agent identity](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. ### Account matching failed diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx index 45e9fae2..b659b1e0 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx @@ -2,8 +2,8 @@ title: insufficient_credits description: >- The principal billed for the run has no remaining credits. Top up the - right pool — the triggering user's, or the team owner's for team or - agent API key and scheduled runs — to continue. + right pool — the triggering user's, or the team owner's for agent API + key and scheduled runs — to continue. --- The `insufficient_credits` error occurs when the principal billed for a cloud agent run has no remaining credits to charge against. @@ -11,7 +11,7 @@ The `insufficient_credits` error occurs when the principal billed for a cloud ag On self-serve plans (Build, Max, Business), the billed principal depends on how the run was triggered: * **User-triggered runs** draw from the triggering user's pool: plan-included credits first, then their user-scoped add-on credits. -* **Team and agent API key, and scheduled runs** draw from the team owner's pool: the owner's plan-included credits first, then the owner's add-on credits. +* **Agent API key and scheduled runs** draw from the team owner's pool: the owner's plan-included credits first, then the owner's add-on credits. When both pools are depleted and [auto-reload](/support-and-community/plans-and-billing/add-on-credits/) is off, new runs return this error. On Enterprise plans, runs draw from the team-scoped credit pool per your contract — contact your account manager when the pool is exhausted. @@ -30,7 +30,7 @@ When both pools are depleted and [auto-reload](/support-and-community/plans-and- This error is returned when: * A user-triggered run runs out of the user's plan-included credits and their user-scoped add-on credits. -* A team or agent API key, or scheduled run, runs out of the team owner's plan-included credits and the owner's add-on credits. +* An agent API key or scheduled run runs out of the team owner's plan-included credits and the owner's add-on credits. * Auto-reload is off, or auto-reload is on but the team-wide monthly spend cap has been reached. For the full waterfall, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. @@ -61,7 +61,7 @@ The fix depends on which principal was billed. 2. Alternatively, enable auto-reload, subject to your team's monthly spend cap. 3. Retry the failed operation. -**For team or agent API key, or scheduled runs (the team owner's pool was exhausted):** +**For agent API key or scheduled runs (the team owner's pool was exhausted):** 1. The team owner tops up their pool: purchase add-on credits or wait for the monthly refresh. 2. If auto-reload is on but the team-wide spend cap was reached, an admin can raise the cap in **Settings** > **Billing and usage**. @@ -73,7 +73,7 @@ If you are not a team admin or the team owner, contact them to top up the right ## Related -* [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Credit billing for individual, team, and agent API key runs. +* [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Credit billing for individual user runs and agent API key runs. * [Add-on credits](/support-and-community/plans-and-billing/add-on-credits/) — Purchase additional credits and configure auto-reload. * [Platform credits](/support-and-community/plans-and-billing/platform-credits/) — The third credit bucket alongside AI credits and compute credits. * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Billing and plan requirements for cloud agents. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 26625ff0..ac165f8a 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -8,19 +8,18 @@ sidebar: API keys let the Oz CLI and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. +:::note +**Naming change:** What used to be called a **team API key** is now an **agent API key**. They behave identically — an agent API key bound to your team's built-in `Default Service Account` [agent identity](/agent-platform/cloud-agents/agents/) has the same billing, GitHub App auth, and headless-run behavior as the legacy team key. The rename reflects that the broader agent identity model is a superset of the old team-key concept. If your Warp desktop app's API key dialog still labels the toggle `Team`, picking it produces an equivalent agent key bound to the `Default Service Account`. The rest of this page uses "agent API key" throughout. +::: + ## API key types -Warp supports three types of API keys, each with different billing and identity behavior: +Warp supports two types of API keys: * **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 and execute under your team's default [agent identity](/agent-platform/cloud-agents/agents/). 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 API keys** - Cloud agent runs execute as a specific [agent identity](/agent-platform/cloud-agents/agents/) you choose at key creation time. Agent keys are a superset of team keys: every team starts with a built-in `Default Service Account` agent identity, and an agent key bound to that identity behaves the same as a team API key (same billing waterfall, same team GitHub App behavior). Create additional agent identities — `ci-runner`, `nightly-jobs`, `on-call` — when you want runs from distinct workflows to be filterable and auditable as that bot in run history. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model. +* **Agent API keys** - Cloud agent runs are not tied to any individual user and execute as a specific [agent identity](/agent-platform/cloud-agents/agents/) you choose at key creation time. Every team starts with a built-in `Default Service Account` agent identity; pick it for the same behavior as the legacy team key. Create additional agent identities — `ci-runner`, `nightly-jobs`, `on-call` — when you want runs from distinct workflows to be filterable and auditable as that bot in run history. 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 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, agent key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model. -Team and agent 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/). - -:::note -**Migrating from a team key to an agent key?** No change is required. An agent API key bound to the `Default Service Account` is functionally identical to a team API key — same downstream billing, same GitHub App resolution, same headless-run behavior. The split into `Personal` / `Team` / `Agent` is a labeling change in the UI; existing team keys continue to work and existing prerequisites that say "create a team-scoped API key" can be satisfied by either option. -::: +Agent 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/). ## Creating API keys @@ -42,9 +41,7 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting 1. In the Warp app, click your profile photo in the top-right corner, then click **Settings**. 2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. 3. In the API Keys section, click **+ Create API Key**. -4. Choose the key type: - * **Personal** - Tied to your individual Warp account. - * **Team** - Tied to your team's default agent identity (`Default Service Account`). Equivalent to creating an agent key bound to the default identity from the Oz web app. +4. Pick **Personal** for a personal key, or **Agent** / **Team** for an agent key bound to your team's `Default Service Account`. See the naming-change note at the top of this page for details. 5. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). 6. Click **Create key**. 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** @@ -55,18 +52,18 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting :::note -To create or manage **named agent identities** (anything beyond the default), use the Oz web app at [oz.warp.dev/agents](https://oz.warp.dev/agents) or the [`oz agent`](/reference/api-and-sdk/) REST endpoints. The Warp desktop app's API key dialog binds team keys to the default identity automatically and does not expose the named-agent picker. +To create or manage **named agent identities** (anything beyond the default), use the Oz web app at [oz.warp.dev/agents](https://oz.warp.dev/agents) or the [`oz agent`](/reference/api-and-sdk/) REST endpoints. The Warp desktop app's API key dialog binds keys to the `Default Service Account` automatically and does not expose the named-agent picker. ::: :::note When an agent needs to make code changes (e.g., opening pull requests, pushing branches, or writing to a repository), you have two options: * Use a **personal API key** to authenticate as you. The agent runs with your GitHub permissions, and code changes are attributed to your GitHub account. -* Use a **team or agent API key** with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured. The agent authenticates with the Oz by Warp GitHub App, and code changes are not attributed to any individual user. +* Use an **agent API key** with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured. The agent authenticates with the Oz by Warp GitHub App, and code changes are attributed to the agent identity rather than any individual user. ::: :::note -Team and agent keys without GitHub App authorization are the right fit for automated workflows that don't require writing to GitHub, such as analysis, monitoring, or triage. +Agent API keys without GitHub App authorization are the right fit for automated workflows that don't require writing to GitHub, such as analysis, monitoring, or triage. ::: ## Authenticating with API keys @@ -96,7 +93,7 @@ The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the W * **Name** - The name you assigned when creating the key * **Key** - A masked suffix (`wk-**xxxx`) to help identify the key -* **Scope** - Whether the key is **Personal**, **Team**, or **Agent**. Agent keys also show which [agent identity](/agent-platform/cloud-agents/agents/) the key is bound to. +* **Scope** - Whether the key is **Personal** or **Agent** (legacy keys may display as **Team**; see the naming-change note at the top of this page). Agent keys also show which [agent identity](/agent-platform/cloud-agents/agents/) the key is bound to. * **Created** - When the key was created * **Last used** - When the key was last used for authentication * **Expires at** - The key's expiration date, or "Never" if it doesn't expire @@ -115,7 +112,7 @@ Deleting a named [agent identity](/agent-platform/cloud-agents/agents/) atomical * **Use environment variables** - Avoid passing API keys directly in commands where they may be logged or visible in shell history. * **Set appropriate expiration** - Use shorter expiration times for development and testing; consider longer durations for stable production workflows. -* **Use team or agent keys for automation** - For CI/CD and scheduled tasks, team and agent keys provide cleaner billing attribution and don't depend on any individual user's account. Pick a named agent identity when you want runs from distinct workflows to be filterable in the dashboard. -* **Use personal keys or configure team GitHub authorization when agents need to write to GitHub** - Personal keys authenticate as you; team and agent keys can also write to GitHub when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured via the Admin Panel. +* **Use agent keys for automation** - For CI/CD and scheduled tasks, agent keys provide cleaner billing attribution and don't depend on any individual user's account. Pick a named agent identity when you want runs from distinct workflows to be filterable in the dashboard. +* **Use personal keys or configure team GitHub authorization when agents need to write to GitHub** - Personal keys authenticate as you; agent keys can also write to GitHub when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured via the Admin Panel. * **Rotate keys periodically** - Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. * **Store securely** - Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index 2bc93a53..505b88ce 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -178,14 +178,14 @@ You typically only need to handle this once per team, unless your repo access ch #### Team-level GitHub authorization -For automated workflows that use a team or [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Oz by Warp GitHub App instead of an individual's personal token. +For automated workflows that use an [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Oz by Warp GitHub App instead of an individual's personal token. -This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with a team or agent API key can clone repos and open pull requests using the GitHub App installation token. +This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with an agent API key can clone repos and open pull requests using the GitHub App installation token. For full setup instructions, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). :::note -**Using API keys:** Personal API keys authenticate as you, so the agent runs with your GitHub permissions and code changes are attributed to your account. Team and agent API keys with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured use the GitHub App token instead. +**Using API keys:** Personal API keys authenticate as you, so the agent runs with your GitHub permissions and code changes are attributed to your account. Agent API keys with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured use the GitHub App token instead. ::: --- diff --git a/src/content/docs/reference/cli/quickstart.mdx b/src/content/docs/reference/cli/quickstart.mdx index 80ebf0c0..ece08db9 100644 --- a/src/content/docs/reference/cli/quickstart.mdx +++ b/src/content/docs/reference/cli/quickstart.mdx @@ -39,7 +39,7 @@ Interactive login works on both **local** and **remote** machines, and does not export WARP_API_KEY="wk-..." ``` -Create an API key in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for guidance on personal, team, and agent keys, and on security best practices. +Create an API key in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. agent keys (and the legacy team-key label) and on security best practices. ::: ## 3. Run an agent diff --git a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx index de43d01d..4de69196 100644 --- a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx @@ -81,7 +81,7 @@ Team admins manage add-on credit settings for the team in **Settings** > **Billi * **Auto-reload** — When enabled, the admin selects an add-on credit denomination for the team. Warp automatically purchases that denomination for any user whose add-on credit balance drops below 100 credits, subject to the team-wide spend cap. While auto-reload is on, individual users cannot purchase add-on credits manually. * **Manual purchases** — When auto-reload is off, eligible team members can purchase add-on credits for themselves, as long as the team stays below the team-wide spend cap. -For how cloud agent runs that aren't initiated by a specific team member (scheduled runs, team or agent API key runs) are billed, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. +For how cloud agent runs that aren't initiated by a specific team member (scheduled runs, agent API key runs) are billed, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. ### Plan changes and cancellations diff --git a/src/content/docs/support-and-community/plans-and-billing/credits.mdx b/src/content/docs/support-and-community/plans-and-billing/credits.mdx index 178e7bb1..a1f00ee8 100644 --- a/src/content/docs/support-and-community/plans-and-billing/credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/credits.mdx @@ -161,6 +161,6 @@ For a full breakdown of how platform credits work, see [platform credits](/suppo ### Cloud agent runs on team plans -Cloud agent runs that aren't initiated by a specific team member — for example, scheduled runs or runs triggered through a team or agent API key — follow plan-specific billing rules. On self-serve plans (Build, Max, Business), these runs are billed to the team owner: the owner's plan-included credits first, then their 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 spend cap. On Enterprise plans, these runs draw from the team-scoped credit pool per your contract. +Cloud agent runs that aren't initiated by a specific team member — for example, scheduled runs or runs triggered through an agent API key — follow plan-specific billing rules. On self-serve plans (Build, Max, Business), these runs are billed to the team owner: the owner's plan-included credits first, then their 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 spend cap. On Enterprise plans, these runs draw from the team-scoped credit pool per your contract. For the full waterfall, see [How are cloud agent runs on team plans billed when no individual user triggered them?](/support-and-community/plans-and-billing/pricing-faqs/#how-are-cloud-agent-runs-on-team-plans-billed-when-no-individual-user-triggered-them) in the Pricing FAQs. diff --git a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx index b48171ee..dcdef4e5 100644 --- a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx @@ -189,10 +189,10 @@ Auto-reload can be enabled, paused, or reconfigured at any time in **Settings** ### 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 or agent 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**. :::caution -Team owners: scheduled runs and runs triggered through a team or agent API key draw from your personal credit pool. If auto-reload is enabled on your account, automated jobs can consume your add-on credits and count toward your spend cap. Review your auto-reload settings and team-wide spend cap in **Settings** > **Billing and usage** before relying on scheduled or API-key-triggered cloud agents. +Team owners: scheduled runs and runs triggered through an agent API key draw from your personal credit pool. If auto-reload is enabled on your account, automated jobs can consume your add-on credits and count toward your spend cap. Review your auto-reload settings and team-wide spend cap in **Settings** > **Billing and usage** before relying on scheduled or API-key-triggered cloud agents. ::: The waterfall on the owner's account is: From 51ea888464abed2308ba890796dc749aced929c0 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 26 May 2026 23:44:10 +0000 Subject: [PATCH 05/12] 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 --- .../agent-platform/cloud-agents/agents.mdx | 63 +++++++++--- .../integrations/github-actions.mdx | 2 +- .../quickstart-github-actions.mdx | 2 +- .../self-hosting/managed-direct.mdx | 2 +- .../self-hosting/managed-docker.mdx | 2 +- .../self-hosting/managed-kubernetes.mdx | 2 +- .../cloud-agents/self-hosting/quickstart.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 4 +- .../team-access-billing-and-identity.mdx | 4 +- .../docs/reference/api-and-sdk/quickstart.mdx | 2 +- src/content/docs/reference/cli/api-keys.mdx | 98 +++++++++++-------- src/content/docs/reference/cli/quickstart.mdx | 2 +- 12 files changed, 118 insertions(+), 67 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 9bcc3877..a6b4a2d1 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -8,13 +8,16 @@ sidebar: label: "Agent identities" --- -An **agent identity** is a team-scoped identity that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity. Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person. +An **agent identity** is a team-scoped bot account that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity (`Default Service Account`). Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot rather than to a person. + +Think of an agent identity like an IAM service account: it has a name, a description, its own set of managed secrets, and its own preloaded skills. When you bind an [API key](/reference/cli/api-keys/) to it, every headless run authenticated by that key executes *as* that bot — with that bot's credentials, that bot's skills, and that bot's name in the dashboard. Agent identities are useful when you want to: -* **Separate workflows** - Give the deploy bot, the dependency-update bot, and the code-review bot distinct identities so runs are easier to filter and audit. -* **Scope credentials** - Attach a specific set of managed secrets and skills to one identity so its runs receive only the configuration that workflow needs. -* **Attribute automated work** - Bind an API key to an agent identity so CI pipelines and webhooks show up as that bot in run history rather than as a teammate. +* **Separate workflows** — Give the deploy bot, the dependency-update bot, and the PR-review bot distinct identities. A `deploy-bot` for production deploys, a `dependabot-runner` for nightly upgrades, a `pr-reviewer` for inline code review. Runs are filterable by identity in the [Oz dashboard](https://oz.warp.dev/runs), and individual run pages show which bot ran the task. +* **Scope credentials** — Attach managed secrets to one identity so its runs receive only the configuration that workflow needs. A `deploy-bot` identity can hold `DEPLOY_TOKEN` and `DATABASE_URL` for production deploys; a `pr-reviewer` identity holds neither, because its runs never need to deploy. +* **Preload skills** — Attach [skill specs](/agent-platform/capabilities/skills/) to an identity so every run starts with the right instructions. A `pr-reviewer` identity preloaded with `org/repo:.warp/skills/code-review/SKILL.md` doesn't need a `--skill` flag at every invocation. +* **Attribute automated work** — CI pipelines, webhooks, and scheduled jobs that authenticate with an agent identity's API key show up in run history as that bot, not as a teammate. Audit trails stay attributable to the workflow, not the person who happened to set up the key. ## How agent identities work @@ -22,9 +25,47 @@ Each team has one default agent identity, called `Default Service Account`. Head You can attach the following configuration to an agent identity: -* **Description** - A short, human-readable summary teammates see when picking the identity. -* **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to. -* **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. +* **Description** — A short, human-readable summary teammates see when picking the identity. +* **Managed secrets** — References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to. +* **Skills** — Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. + +## Quickstart: create a custom agent identity + +This walkthrough creates a `deploy-bot` identity, gives it a deploy secret and a deploy skill, generates an API key bound to it, and uses that key to trigger a run that shows up in the dashboard attributed to `deploy-bot`. + +1. **Create a managed secret** the identity will need (skip if your team already has one). In the [Oz web app](https://oz.warp.dev/secrets), add a `DEPLOY_TOKEN` team-scoped secret. See [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) for the full secret-management flow. +2. **Create the agent identity.** Send a `POST` to `/api/v1/agent/identities` with your existing API key (or use the Agents page at [oz.warp.dev/agents](https://oz.warp.dev/agents) once it's wired up to a UI): + + ```bash + curl -X POST https://app.warp.dev/api/v1/agent/identities \ + -H "Authorization: Bearer $WARP_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "deploy-bot", + "description": "Handles production deploys off main.", + "secrets": [{"name": "DEPLOY_TOKEN"}], + "skills": ["warpdotdev/warp-server:.claude/skills/deploy/SKILL.md"] + }' + ``` + + **Expected outcome:** A `201 Created` response with the new identity's `uid`, `name`, and `available: true`. +3. **Generate an API key bound to the identity.** In [oz.warp.dev/settings](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, select `deploy-bot` from the dropdown, name the key, and copy the raw value. See [API keys](/reference/cli/api-keys/) for the full creation flow. +4. **Use the key to run an agent.** Export the key and trigger a run — the agent will have `DEPLOY_TOKEN` injected automatically and the `deploy` skill preloaded: + + ```bash + export WARP_API_KEY="wk-..." + oz agent run-cloud --environment --prompt "Deploy the latest main to production" + ``` + +5. **Confirm attribution.** Open the [Oz dashboard](https://oz.warp.dev/runs) and filter by agent identity. The run shows up under `deploy-bot`, not under your user account. + +The same pattern works for any per-workflow identity: a `pr-reviewer` identity with read-only GitHub access and a code-review skill, a `nightly-jobs` identity used by scheduled cleanups, an `on-call` identity that holds incident-playbook skills and production credentials. + +## Agent API keys + +An **agent API key** is the credential that lets a headless caller execute as a specific agent identity. The key is bound to one identity at creation time and inherits that identity's secrets and skills for every run. + +See [API keys](/reference/cli/api-keys/) for the full creation flow, the per-surface (Oz web app vs. Warp desktop app) differences, and the relationship to legacy "team API keys." ## Service accounts and agent identities @@ -66,14 +107,6 @@ A few constraints apply across every endpoint: * **Human callers only** - Only human users can create, update, or delete an agent identity. A request authenticated as an agent identity itself is rejected. * **Availability is enforced on use** - Over-plan-limit identities are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs. -## API keys bound to an agent identity - -An agent API key is bound to a specific agent identity at creation time — the Oz web app's key dialog calls this the **Agent** key type. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key. - -To create a key bound to a specific identity, choose the identity in the Oz web app's New API key dialog. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between personal and agent keys, including the note on the legacy team-key label. - -Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself. - ## Running as an agent identity There are two ways to run a cloud agent as a specific agent identity: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index b4f7c4c2..7ae28b49 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -41,7 +41,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Personal and agent keys both work; see [API keys](/reference/cli/api-keys/) for the differences and when to pick each. +* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key for commits attributed to you, or an [agent key](/agent-platform/cloud-agents/agents/) bound to a workflow-scoped identity for headless runs. See [API keys](/reference/cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx index d492bf96..4f66ed63 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx @@ -13,7 +13,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. Personal and agent keys both work; use a personal key if the agent needs to write to your repo as you, or an agent key with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for headless workflows. See [API Keys](/reference/cli/api-keys/) for details, including the note on the legacy team-key label. +* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key bound to an [agent identity](/agent-platform/cloud-agents/agents/) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for headless workflows. See [API Keys](/reference/cli/api-keys/) for the full creation flow and principal selection. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx index b8bb118a..dfce4d34 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx @@ -39,7 +39,7 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx index f91e540d..cf284ee4 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx @@ -26,7 +26,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx index 136d8a7a..a00fdc1c 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx @@ -38,7 +38,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx index 8435cefa..104c6da8 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx @@ -19,7 +19,7 @@ This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/ * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **An agent API key** — In the [Oz web app](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, and bind it to the built-in `Default Service Account` agent identity. The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index 538322f1..a80f2bb6 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -2,7 +2,7 @@ title: Unmanaged architecture description: >- Run agents in your existing CI, Kubernetes, or dev environments using - the oz agent run CLI with Warp tracking and observability. + the `oz agent run` CLI with Warp tracking and observability. sidebar: label: "Unmanaged" --- @@ -33,7 +33,7 @@ No Docker, no worker daemon, no environment required — just the Oz CLI on any ### Prerequisites * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings) (click **New API key**, pick **Agent**, bind it to the built-in `Default Service Account`). The Warp desktop app's equivalent toggle may still show **Team**; see [API Keys](/reference/cli/api-keys/) for the naming-change note and full creation flow. +* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` (or a custom [agent identity](/agent-platform/cloud-agents/agents/) for workflow-scoped attribution). See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index 467383db..6a40f8dc 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -140,7 +140,7 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use an agent API key.** Tasks initiated with an agent API key (or a legacy team API key created in the Warp desktop app, which is equivalent to an agent key bound to the `Default Service Account`) now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. +3. **Use an agent API key.** Tasks initiated with an agent API key bound to any [agent identity](/agent-platform/cloud-agents/agents/) on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. Code changes are attributed to the agent identity (or to the `Default Service Account` for legacy team keys). ### How this relates to environments @@ -156,7 +156,7 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm Team GitHub authorization is complementary to the existing personal token flow: * **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. -* **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 (the `Default Service Account` for legacy team keys) rather than any individual user. +* **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](/agent-platform/cloud-agents/agents/) the key is bound to (the `Default Service Account` for legacy team keys) rather than any individual user. Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with an agent API key. diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index 5ef87d30..9f6b7484 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -17,7 +17,7 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe ## Prerequisites -* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys**, then copy the raw value. Personal and agent keys both authenticate API requests — see [API Keys](/reference/cli/api-keys/) for step-by-step instructions and when to pick each type. +* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) and copy the raw value. Use a personal key for personal-attribution workflows, or an [agent key](/agent-platform/cloud-agents/agents/) bound to a team-scoped identity for headless automation. See [API Keys](/reference/cli/api-keys/) for the full flow. * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) first. --- diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index ac165f8a..fa308563 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -8,40 +8,62 @@ sidebar: API keys let the Oz CLI and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. -:::note -**Naming change:** What used to be called a **team API key** is now an **agent API key**. They behave identically — an agent API key bound to your team's built-in `Default Service Account` [agent identity](/agent-platform/cloud-agents/agents/) has the same billing, GitHub App auth, and headless-run behavior as the legacy team key. The rename reflects that the broader agent identity model is a superset of the old team-key concept. If your Warp desktop app's API key dialog still labels the toggle `Team`, picking it produces an equivalent agent key bound to the `Default Service Account`. The rest of this page uses "agent API key" throughout. -::: +## Principals: personal or agent + +Every API key authenticates as a **principal** — either you (the human) or an [agent identity](/agent-platform/cloud-agents/agents/) (a team-scoped bot account). The choice of principal determines who runs are attributed to, which credentials they inherit, and how billing is charged. Pick the principal that matches the workflow, then create the key. + +* **Personal API keys** authenticate as you. Runs execute with your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agent-platform/capabilities/skills/). Use a personal key when the headless workflow should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys. +* **Agent API keys** authenticate as a specific [agent identity](/agent-platform/cloud-agents/agents/) on your team. The key is bound to one identity at creation time. Runs inherit that identity's name, managed secrets, and skills, and show up in the [Oz dashboard](https://oz.warp.dev) attributed to that bot rather than to a person. + +## Agent identities power agent API keys -## API key types +An agent identity is a named bot account that your whole team can share. Each identity carries: -Warp supports two types of API keys: +* **A name** — like `deploy-bot`, `pr-reviewer`, or `nightly-jobs`. Visible in the Agent picker, in run filters, and on every run that executes as it. +* **A description** — a short summary teammates see when picking the identity. +* **Managed secrets** — references (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to. A `deploy-bot` identity can hold `DEPLOY_TOKEN` and `DATABASE_URL`; a `pr-reviewer` identity doesn't see them. +* **Skills** — [skill specs](/agent-platform/capabilities/skills/) (e.g., `org/repo:.claude/skills/deploy/SKILL.md`) the identity comes preloaded with, so every run starts with the right instructions. +* **Plan-limit availability** — how many identities a team can use depends on the plan. See [Agent identities](/agent-platform/cloud-agents/agents/#plan-limits). -* **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. -* **Agent API keys** - Cloud agent runs are not tied to any individual user and execute as a specific [agent identity](/agent-platform/cloud-agents/agents/) you choose at key creation time. Every team starts with a built-in `Default Service Account` agent identity; pick it for the same behavior as the legacy team key. Create additional agent identities — `ci-runner`, `nightly-jobs`, `on-call` — when you want runs from distinct workflows to be filterable and auditable as that bot in run history. 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 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, agent key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model. +The payoff of binding an agent API key to a specific identity is **scoped automation**: the `deploy-bot` key can deploy because it inherits `DEPLOY_TOKEN`; the `pr-reviewer` key cannot, because its identity doesn't have the secret. Credentials and behavior are isolated per workflow, runs in the dashboard are filterable by which bot ran them, and you can rotate or revoke one workflow's access without touching the rest. -Agent 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/). +See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model — creating identities, attaching secrets and skills, and managing them via the public API. + +## The Default Service Account + +Every team starts with a built-in agent identity called `Default Service Account`. It's the no-config baseline: it has no attached secrets or skills, and headless runs that don't explicitly bind to a custom identity execute as it. + +An agent API key bound to the `Default Service Account` is the simplest case of an agent key — it works for most teams that just want a single shared bot for automation. As you add named identities for specific workflows, the default keeps serving as the catch-all for runs that don't pick one. + +:::note +**Legacy "team API key" terminology.** Older docs, older Warp client versions, and some onboarding materials refer to what is now an agent API key bound to the `Default Service Account` as a "team API key." The two are the same key — the rename reflects that agent identities are now a first-class concept, not just a single auto-created service account. If your Warp desktop app's API key dialog still labels the toggle **Team**, picking it creates an agent API key bound to the `Default Service Account`. +::: -## Creating API keys +## Creating an API key -You can create an API key in either the [Oz web app](https://oz.warp.dev/settings) or the Warp desktop app. The two surfaces produce keys that authenticate the CLI and SDK identically. +You can create an API key in either the [Oz web app](https://oz.warp.dev/settings) or the Warp desktop app. Both surfaces produce keys that authenticate the CLI and SDK identically. ### From the Oz web app (recommended) -1. Open the Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings). +The Oz web app is the only surface where you can bind a key to a specific agent identity. If you want a workflow-scoped key (e.g., `deploy-bot`), [create the identity](/agent-platform/cloud-agents/agents/) first. + +1. Open [oz.warp.dev/settings](https://oz.warp.dev/settings). 2. In the API Keys section, click **New API key**. -3. Choose the key type: - * **Personal** - Tied to your individual Warp account. - * **Agent** - Tied to a specific [agent identity](/agent-platform/cloud-agents/agents/) on your team. The dropdown lists every available identity, including the built-in `Default Service Account`. Pick the default identity when you want behavior identical to a traditional team key, or a named identity for workflow-scoped attribution. -4. Enter a name and choose an expiration (1 day, 30 days, 90 days, or never). +3. Choose the principal: + * **Personal** — Tied to your individual Warp account. + * **Agent** — Tied to a specific agent identity on your team. Pick an identity from the dropdown. The list always includes the `Default Service Account` and any custom identities the team has created. +4. Enter a name for the key and choose an expiration (1 day, 30 days, 90 days, or never). 5. Click **Create key**. 6. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** ### From the Warp desktop app +The Warp desktop app binds agent keys to the `Default Service Account` automatically — it does not expose the named-identity picker. To bind a key to a custom identity, use the Oz web app instead. + 1. In the Warp app, click your profile photo in the top-right corner, then click **Settings**. 2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. 3. In the API Keys section, click **+ Create API Key**. -4. Pick **Personal** for a personal key, or **Agent** / **Team** for an agent key bound to your team's `Default Service Account`. See the naming-change note at the top of this page for details. +4. Pick **Personal** for a personal key, or **Agent** / **Team** for an agent key bound to your team's `Default Service Account`. 5. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). 6. Click **Create key**. 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** @@ -51,24 +73,19 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting
API key management interface in Warp settings.
-:::note -To create or manage **named agent identities** (anything beyond the default), use the Oz web app at [oz.warp.dev/agents](https://oz.warp.dev/agents) or the [`oz agent`](/reference/api-and-sdk/) REST endpoints. The Warp desktop app's API key dialog binds keys to the `Default Service Account` automatically and does not expose the named-agent picker. -::: +## Billing and GitHub authorization -:::note -When an agent needs to make code changes (e.g., opening pull requests, pushing branches, or writing to a repository), you have two options: +How a run is billed and which GitHub permissions it gets are determined by the principal the key authenticates as. -* Use a **personal API key** to authenticate as you. The agent runs with your GitHub permissions, and code changes are attributed to your GitHub account. -* Use an **agent API key** with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured. The agent authenticates with the Oz by Warp GitHub App, and code changes are attributed to the agent identity rather than any individual user. -::: +**Personal keys.** Runs execute as you, with your GitHub permissions and your account's credit pool. On Build, Max, and Business plans, the 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, per your Enterprise contract terms. Code changes are attributed to your GitHub account. -:::note -Agent API keys without GitHub App authorization are the right fit for automated workflows that don't require writing to GitHub, such as analysis, monitoring, or triage. -::: +**Agent keys.** Runs execute as the bound agent identity, which is team-scoped. 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: agent identities authenticate via the **Oz by Warp** GitHub App when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured — commits are attributed to the agent identity (or to the `Default Service Account` for legacy team keys). Without team GitHub authorization, agent keys can still run agents that don't need to write to GitHub (analysis, monitoring, triage). + +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/). ## Authenticating with API keys -You can authenticate with an API key in the CLI using either an environment variable or command flag. We recommend environment variables for security and easier reuse across multiple commands. +You can authenticate with an API key in the CLI using either an environment variable or a command flag. We recommend environment variables for security and easier reuse across multiple commands. **Via environment variable (recommended):** @@ -91,12 +108,12 @@ API keys start with the prefix `wk-`. If your key doesn't have this prefix, it m The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the Warp app's **Settings** > **Cloud platform** > **Oz Cloud API Keys** both display your active keys with the following information: -* **Name** - The name you assigned when creating the key -* **Key** - A masked suffix (`wk-**xxxx`) to help identify the key -* **Scope** - Whether the key is **Personal** or **Agent** (legacy keys may display as **Team**; see the naming-change note at the top of this page). Agent keys also show which [agent identity](/agent-platform/cloud-agents/agents/) the key is bound to. -* **Created** - When the key was created -* **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. +* **Scope** — The principal the key authenticates as. Personal keys show your user; agent keys show the agent identity the key is bound to (the `Default Service Account` for legacy team keys, or whichever named identity you picked). Legacy keys may display as **Team** in the Warp desktop app. +* **Created** — When the key was created. +* **Last used** — When the key was last used for authentication. +* **Expires at** — The key's expiration date, or "Never" if it doesn't expire. ### Deleting API keys @@ -110,9 +127,10 @@ Deleting a named [agent identity](/agent-platform/cloud-agents/agents/) atomical ## Best practices -* **Use environment variables** - Avoid passing API keys directly in commands where they may be logged or visible in shell history. -* **Set appropriate expiration** - Use shorter expiration times for development and testing; consider longer durations for stable production workflows. -* **Use agent keys for automation** - For CI/CD and scheduled tasks, agent keys provide cleaner billing attribution and don't depend on any individual user's account. Pick a named agent identity when you want runs from distinct workflows to be filterable in the dashboard. -* **Use personal keys or configure team GitHub authorization when agents need to write to GitHub** - Personal keys authenticate as you; agent keys can also write to GitHub when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured via the Admin Panel. -* **Rotate keys periodically** - Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. -* **Store securely** - Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. +* **Pick the agent identity that matches the workflow** — Instead of using one shared `Default Service Account` key everywhere, create a custom identity per workflow (deploy bot, PR reviewer, dependency upgrader) and bind one key to each. Runs become filterable by identity, credentials stay scoped to the workflow that needs them, and rotation only affects the one workflow. +* **Use personal keys for personal-attribution workflows** — When a headless run should act on your behalf and code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys when the run is automation that runs without a specific person behind it. +* **Use environment variables** — Avoid passing API keys directly in commands where they may be logged or visible in shell history. +* **Set appropriate expiration** — Use shorter expiration times for development and testing; consider longer durations for stable production workflows. +* **Configure team GitHub authorization for agents that write to GitHub** — Personal keys authenticate as you with your GitHub permissions. Agent keys authenticate via the [Oz by Warp GitHub App](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) when team GitHub authorization is configured in the Admin Panel. +* **Rotate keys periodically** — Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. +* **Store securely** — Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. diff --git a/src/content/docs/reference/cli/quickstart.mdx b/src/content/docs/reference/cli/quickstart.mdx index ece08db9..9233f330 100644 --- a/src/content/docs/reference/cli/quickstart.mdx +++ b/src/content/docs/reference/cli/quickstart.mdx @@ -39,7 +39,7 @@ Interactive login works on both **local** and **remote** machines, and does not export WARP_API_KEY="wk-..." ``` -Create an API key in the [Oz web app](https://oz.warp.dev/settings) or in the Warp app under **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. agent keys (and the legacy team-key label) and on security best practices. +Create an API key in the [Oz web app](https://oz.warp.dev/settings). See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. [agent keys](/agent-platform/cloud-agents/agents/) and on security best practices. ::: ## 3. Run an agent From 5245b2fe1b837a7a82e42fc4c6e9bda71bcc28ac Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 00:01:13 +0000 Subject: [PATCH 06/12] Disentangle GitHub-side commit attribution from Oz-side run identity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../cloud-agents/team-access-billing-and-identity.mdx | 4 ++-- src/content/docs/reference/cli/api-keys.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index 6a40f8dc..d54de49c 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -140,7 +140,7 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use an agent API key.** Tasks initiated with an agent API key bound to any [agent identity](/agent-platform/cloud-agents/agents/) on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. Code changes are attributed to the agent identity (or to the `Default Service Account` for legacy team keys). +3. **Use an agent API key.** Tasks initiated with an agent API key bound to any [agent identity](/agent-platform/cloud-agents/agents/) on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Oz by Warp GitHub App rather than any individual user; in the Oz dashboard, the run is attributed to the bound agent identity (or to the `Default Service Account` for legacy team keys). ### How this relates to environments @@ -156,7 +156,7 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm Team GitHub authorization is complementary to the existing personal token flow: * **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. -* **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](/agent-platform/cloud-agents/agents/) the key is bound to (the `Default Service Account` for legacy team keys) rather than any individual user. +* **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Oz by Warp GitHub App rather than any individual user. In the Oz dashboard, the run is attributed to the bound [agent identity](/agent-platform/cloud-agents/agents/) (the `Default Service Account` for legacy team keys), which controls run filtering and audit attribution on the Warp side. Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with an agent API key. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index fa308563..2b658c19 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -79,7 +79,7 @@ How a run is billed and which GitHub permissions it gets are determined by the p **Personal keys.** Runs execute as you, with your GitHub permissions and your account's credit pool. On Build, Max, and Business plans, the 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, per your Enterprise contract terms. Code changes are attributed to your GitHub account. -**Agent keys.** Runs execute as the bound agent identity, which is team-scoped. 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: agent identities authenticate via the **Oz by Warp** GitHub App when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured — commits are attributed to the agent identity (or to the `Default Service Account` for legacy team keys). Without team GitHub authorization, agent keys can still run agents that don't need to write to GitHub (analysis, monitoring, triage). +**Agent keys.** Runs execute as the bound agent identity, which is team-scoped. 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: agent identities authenticate via the **Oz by Warp** GitHub App when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured — commits and pull requests are opened by the GitHub App's bot user on GitHub, and the Oz dashboard attributes the run to the bound agent identity (the `Default Service Account` for legacy team keys). Without team GitHub authorization, agent keys can still run agents that don't need to write to GitHub (analysis, monitoring, triage). 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/). From c428a9493d9582149e44a5d4f662b396a2160ee2 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 00:32:07 +0000 Subject: [PATCH 07/12] 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 --- src/content/docs/agent-platform/cloud-agents/agents.mdx | 8 ++++---- .../cloud-agents/integrations/github-actions.mdx | 2 +- .../integrations/quickstart-github-actions.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 2 +- .../cloud-agents/team-access-billing-and-identity.mdx | 2 +- src/content/docs/reference/api-and-sdk/quickstart.mdx | 2 +- src/content/docs/reference/cli/api-keys.mdx | 8 ++++---- 7 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index a6b4a2d1..dc5e8dc3 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -10,7 +10,7 @@ sidebar: An **agent identity** is a team-scoped bot account that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity (`Default Service Account`). Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot rather than to a person. -Think of an agent identity like an IAM service account: it has a name, a description, its own set of managed secrets, and its own preloaded skills. When you bind an [API key](/reference/cli/api-keys/) to it, every headless run authenticated by that key executes *as* that bot — with that bot's credentials, that bot's skills, and that bot's name in the dashboard. +Think of an agent identity like an IAM service account: it has a name, a description, its own set of managed secrets, and its own preloaded skills. When you bind an [API key](/reference/cli/api-keys/) to it, every automated run authenticated by that key executes *as* that bot — with that bot's credentials, that bot's skills, and that bot's name in the dashboard. Agent identities are useful when you want to: @@ -21,7 +21,7 @@ Agent identities are useful when you want to: ## How agent identities work -Each team has one default agent identity, called `Default Service Account`. Headless runs (such as agent API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. +Each team has one default agent identity, called `Default Service Account`. Automated runs (such as agent API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. You can attach the following configuration to an agent identity: @@ -63,7 +63,7 @@ The same pattern works for any per-workflow identity: a `pr-reviewer` identity w ## Agent API keys -An **agent API key** is the credential that lets a headless caller execute as a specific agent identity. The key is bound to one identity at creation time and inherits that identity's secrets and skills for every run. +An **agent API key** is the credential that lets an automated caller (CI, scheduler, webhook handler) execute as a specific agent identity. The key is bound to one identity at creation time and inherits that identity's secrets and skills for every run. See [API keys](/reference/cli/api-keys/) for the full creation flow, the per-surface (Oz web app vs. Warp desktop app) differences, and the relationship to legacy "team API keys." @@ -114,7 +114,7 @@ There are two ways to run a cloud agent as a specific agent identity: * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. -When neither path is used, headless runs (agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. +When neither path is used, automated runs (agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. ## Where agent identities appear in the product diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 7ae28b49..77f78b44 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -41,7 +41,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key for commits attributed to you, or an [agent key](/agent-platform/cloud-agents/agents/) bound to a workflow-scoped identity for headless runs. See [API keys](/reference/cli/api-keys/) for when to pick each. +* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an [agent key](/agent-platform/cloud-agents/agents/) for automated runs (no specific user behind them). See [API keys](/reference/cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx index 4f66ed63..7d8a13df 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx @@ -13,7 +13,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key bound to an [agent identity](/agent-platform/cloud-agents/agents/) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for headless workflows. See [API Keys](/reference/cli/api-keys/) for the full creation flow and principal selection. +* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key bound to an [agent identity](/agent-platform/cloud-agents/agents/) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for automated runs. See [API Keys](/reference/cli/api-keys/) for the full creation flow and principal selection. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index a80f2bb6..08d03387 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -33,7 +33,7 @@ No Docker, no worker daemon, no environment required — just the Oz CLI on any ### Prerequisites * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` (or a custom [agent identity](/agent-platform/cloud-agents/agents/) for workflow-scoped attribution). See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. +* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` (or a custom [agent identity](/agent-platform/cloud-agents/agents/) so runs are attributed to a specific bot). See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index d54de49c..aa2923dc 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -219,7 +219,7 @@ How credits are consumed depends on how the agent run is triggered and authentic * On Build, Max, and Business plans, credits are consumed starting with any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) allocated to the user, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user. * On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms. -**Agent API key and scheduled cloud agent runs** (fully automated or headless workflows): +**Agent API key and scheduled cloud agent runs** (fully automated workflows): * 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. With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index 9f6b7484..aac13682 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -17,7 +17,7 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe ## Prerequisites -* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) and copy the raw value. Use a personal key for personal-attribution workflows, or an [agent key](/agent-platform/cloud-agents/agents/) bound to a team-scoped identity for headless automation. See [API Keys](/reference/cli/api-keys/) for the full flow. +* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) and copy the raw value. Use a personal key if you want runs attributed to you, or an [agent key](/agent-platform/cloud-agents/agents/) for automated runs (no specific user behind them). See [API Keys](/reference/cli/api-keys/) for the full flow. * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) first. --- diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 2b658c19..90555a55 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -12,7 +12,7 @@ API keys let the Oz CLI and cloud agents authenticate without human interaction. Every API key authenticates as a **principal** — either you (the human) or an [agent identity](/agent-platform/cloud-agents/agents/) (a team-scoped bot account). The choice of principal determines who runs are attributed to, which credentials they inherit, and how billing is charged. Pick the principal that matches the workflow, then create the key. -* **Personal API keys** authenticate as you. Runs execute with your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agent-platform/capabilities/skills/). Use a personal key when the headless workflow should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys. +* **Personal API keys** authenticate as you. Runs execute with your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agent-platform/capabilities/skills/). Use a personal key when the automated workflow should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys. * **Agent API keys** authenticate as a specific [agent identity](/agent-platform/cloud-agents/agents/) on your team. The key is bound to one identity at creation time. Runs inherit that identity's name, managed secrets, and skills, and show up in the [Oz dashboard](https://oz.warp.dev) attributed to that bot rather than to a person. ## Agent identities power agent API keys @@ -31,7 +31,7 @@ See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model ## The Default Service Account -Every team starts with a built-in agent identity called `Default Service Account`. It's the no-config baseline: it has no attached secrets or skills, and headless runs that don't explicitly bind to a custom identity execute as it. +Every team starts with a built-in agent identity called `Default Service Account`. It's the no-config baseline: it has no attached secrets or skills, and automated runs that don't pick a specific identity execute as it. An agent API key bound to the `Default Service Account` is the simplest case of an agent key — it works for most teams that just want a single shared bot for automation. As you add named identities for specific workflows, the default keeps serving as the catch-all for runs that don't pick one. @@ -45,7 +45,7 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting ### From the Oz web app (recommended) -The Oz web app is the only surface where you can bind a key to a specific agent identity. If you want a workflow-scoped key (e.g., `deploy-bot`), [create the identity](/agent-platform/cloud-agents/agents/) first. +The Oz web app is the only surface where you can bind a key to a specific agent identity. If you want a key for a specific bot (e.g., `deploy-bot`), [create the identity](/agent-platform/cloud-agents/agents/) first. 1. Open [oz.warp.dev/settings](https://oz.warp.dev/settings). 2. In the API Keys section, click **New API key**. @@ -128,7 +128,7 @@ Deleting a named [agent identity](/agent-platform/cloud-agents/agents/) atomical ## Best practices * **Pick the agent identity that matches the workflow** — Instead of using one shared `Default Service Account` key everywhere, create a custom identity per workflow (deploy bot, PR reviewer, dependency upgrader) and bind one key to each. Runs become filterable by identity, credentials stay scoped to the workflow that needs them, and rotation only affects the one workflow. -* **Use personal keys for personal-attribution workflows** — When a headless run should act on your behalf and code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys when the run is automation that runs without a specific person behind it. +* **Use personal keys for personal-attribution workflows** — When an automated run should act on your behalf and code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys when the run is automation that runs without a specific person behind it. * **Use environment variables** — Avoid passing API keys directly in commands where they may be logged or visible in shell history. * **Set appropriate expiration** — Use shorter expiration times for development and testing; consider longer durations for stable production workflows. * **Configure team GitHub authorization for agents that write to GitHub** — Personal keys authenticate as you with your GitHub permissions. Agent keys authenticate via the [Oz by Warp GitHub App](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) when team GitHub authorization is configured in the Admin Panel. From b57a771b4daa18888577e75cebc726d68dc801cc Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 00:50:40 +0000 Subject: [PATCH 08/12] Senior copywriter pass: rename to 'cloud agents', drop Default Service Account, fix principal differentiation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../agent-platform/cloud-agents/agents.mdx | 126 ++++++++---------- .../integrations/github-actions.mdx | 2 +- .../quickstart-github-actions.mdx | 2 +- .../self-hosting/managed-direct.mdx | 2 +- .../self-hosting/managed-docker.mdx | 2 +- .../self-hosting/managed-kubernetes.mdx | 2 +- .../cloud-agents/self-hosting/quickstart.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 2 +- .../team-access-billing-and-identity.mdx | 4 +- .../docs/reference/api-and-sdk/quickstart.mdx | 2 +- .../external-authentication-required.mdx | 2 +- src/content/docs/reference/cli/api-keys.mdx | 68 ++++------ 12 files changed, 97 insertions(+), 119 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index dc5e8dc3..634be918 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -1,40 +1,37 @@ --- -title: Agent identities +title: Agents description: >- - Agent identities are team-scoped bot accounts that own and execute cloud - agent runs. Separate workflows, scope credentials, and attribute automated - work. + Cloud agents are team-scoped bots that run automation in Oz. Create + named agents per workflow to separate credentials, preload skills, and + attribute runs. sidebar: - label: "Agent identities" + label: "Agents" --- -An **agent identity** is a team-scoped bot account that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity (`Default Service Account`). Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot rather than to a person. +A **cloud agent** is a named bot your team can share. It has its own credentials and skills, and any run it executes shows up in the dashboard attributed to that bot rather than to a person. Bind an [API key](/reference/cli/api-keys/) to one and CI pipelines, scheduled jobs, and webhooks can all act as that bot. -Think of an agent identity like an IAM service account: it has a name, a description, its own set of managed secrets, and its own preloaded skills. When you bind an [API key](/reference/cli/api-keys/) to it, every automated run authenticated by that key executes *as* that bot — with that bot's credentials, that bot's skills, and that bot's name in the dashboard. +Create a named agent per workflow when you want to: -Agent identities are useful when you want to: +* **Separate workflows.** A `deploy-bot` for production deploys, a `dependabot-runner` for nightly upgrades, a `pr-reviewer` for inline code review. Runs are filterable by agent in the [Oz dashboard](https://oz.warp.dev/runs), and each run page shows which bot did the work. +* **Scope credentials.** Attach managed secrets to one agent so only its runs receive them. `deploy-bot` can hold `DEPLOY_TOKEN` and `DATABASE_URL` for production deploys; `pr-reviewer` doesn't see either, because its runs never need to deploy. +* **Preload skills.** Attach [skill specs](/agent-platform/capabilities/skills/) to an agent so every run starts with the right instructions. A `pr-reviewer` preloaded with `org/repo:.warp/skills/code-review/SKILL.md` doesn't need `--skill` on every invocation. +* **Attribute automated work.** CI pipelines, webhooks, and scheduled jobs authenticated by an agent's API key show up in run history as that bot, not as a teammate. Audit trails stay attributable to the workflow, not the person who happened to set up the key. -* **Separate workflows** — Give the deploy bot, the dependency-update bot, and the PR-review bot distinct identities. A `deploy-bot` for production deploys, a `dependabot-runner` for nightly upgrades, a `pr-reviewer` for inline code review. Runs are filterable by identity in the [Oz dashboard](https://oz.warp.dev/runs), and individual run pages show which bot ran the task. -* **Scope credentials** — Attach managed secrets to one identity so its runs receive only the configuration that workflow needs. A `deploy-bot` identity can hold `DEPLOY_TOKEN` and `DATABASE_URL` for production deploys; a `pr-reviewer` identity holds neither, because its runs never need to deploy. -* **Preload skills** — Attach [skill specs](/agent-platform/capabilities/skills/) to an identity so every run starts with the right instructions. A `pr-reviewer` identity preloaded with `org/repo:.warp/skills/code-review/SKILL.md` doesn't need a `--skill` flag at every invocation. -* **Attribute automated work** — CI pipelines, webhooks, and scheduled jobs that authenticate with an agent identity's API key show up in run history as that bot, not as a teammate. Audit trails stay attributable to the workflow, not the person who happened to set up the key. +## What you can configure -## How agent identities work +Each cloud agent has: -Each team has one default agent identity, called `Default Service Account`. Automated runs (such as agent API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. +* **Name** — Like `deploy-bot`, `pr-reviewer`, or `nightly-jobs`. Visible in the Agent picker, in run filters, and on every run that executes as it. +* **Description** — A short summary teammates see when picking the agent. +* **Managed secrets** — References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the agent should have access to. +* **Skills** — Skill specs (for example, `org/repo:path/to/SKILL.md`) the agent comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. -You can attach the following configuration to an agent identity: +## Quickstart: create a custom cloud agent -* **Description** — A short, human-readable summary teammates see when picking the identity. -* **Managed secrets** — References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to. -* **Skills** — Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. +This walkthrough creates a `deploy-bot` agent, gives it a deploy secret and a deploy skill, generates an API key bound to it, and uses that key to trigger a run that shows up in the dashboard attributed to `deploy-bot`. -## Quickstart: create a custom agent identity - -This walkthrough creates a `deploy-bot` identity, gives it a deploy secret and a deploy skill, generates an API key bound to it, and uses that key to trigger a run that shows up in the dashboard attributed to `deploy-bot`. - -1. **Create a managed secret** the identity will need (skip if your team already has one). In the [Oz web app](https://oz.warp.dev/secrets), add a `DEPLOY_TOKEN` team-scoped secret. See [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) for the full secret-management flow. -2. **Create the agent identity.** Send a `POST` to `/api/v1/agent/identities` with your existing API key (or use the Agents page at [oz.warp.dev/agents](https://oz.warp.dev/agents) once it's wired up to a UI): +1. **Create a managed secret** the agent will need (skip if your team already has one). In the [Oz web app](https://oz.warp.dev/secrets), add a `DEPLOY_TOKEN` team-scoped secret. See [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) for the full secret-management flow. +2. **Create the cloud agent.** Send a `POST` to `/api/v1/agent/identities` with your existing API key (or use the Agents page at [oz.warp.dev/agents](https://oz.warp.dev/agents) once it's wired up to a UI): ```bash curl -X POST https://app.warp.dev/api/v1/agent/identities \ @@ -48,8 +45,8 @@ This walkthrough creates a `deploy-bot` identity, gives it a deploy secret and a }' ``` - **Expected outcome:** A `201 Created` response with the new identity's `uid`, `name`, and `available: true`. -3. **Generate an API key bound to the identity.** In [oz.warp.dev/settings](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, select `deploy-bot` from the dropdown, name the key, and copy the raw value. See [API keys](/reference/cli/api-keys/) for the full creation flow. + **Expected outcome:** A `201 Created` response with the new agent's `uid`, `name`, and `available: true`. +3. **Generate an API key bound to the agent.** In [oz.warp.dev/settings](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, select `deploy-bot` from the dropdown, name the key, and copy the raw value. See [API keys](/reference/cli/api-keys/) for the full creation flow. 4. **Use the key to run an agent.** Export the key and trigger a run — the agent will have `DEPLOY_TOKEN` injected automatically and the `deploy` skill preloaded: ```bash @@ -57,80 +54,73 @@ This walkthrough creates a `deploy-bot` identity, gives it a deploy secret and a oz agent run-cloud --environment --prompt "Deploy the latest main to production" ``` -5. **Confirm attribution.** Open the [Oz dashboard](https://oz.warp.dev/runs) and filter by agent identity. The run shows up under `deploy-bot`, not under your user account. +5. **Confirm attribution.** Open the [Oz dashboard](https://oz.warp.dev/runs) and filter by agent. The run shows up under `deploy-bot`, not under your user account. -The same pattern works for any per-workflow identity: a `pr-reviewer` identity with read-only GitHub access and a code-review skill, a `nightly-jobs` identity used by scheduled cleanups, an `on-call` identity that holds incident-playbook skills and production credentials. +The same pattern works for any per-workflow bot: a `pr-reviewer` with read-only GitHub access and a code-review skill, a `nightly-jobs` agent used by scheduled cleanups, an `on-call` agent that holds incident-playbook skills and production credentials. ## Agent API keys -An **agent API key** is the credential that lets an automated caller (CI, scheduler, webhook handler) execute as a specific agent identity. The key is bound to one identity at creation time and inherits that identity's secrets and skills for every run. - -See [API keys](/reference/cli/api-keys/) for the full creation flow, the per-surface (Oz web app vs. Warp desktop app) differences, and the relationship to legacy "team API keys." +An **agent API key** is the credential that lets CI, schedulers, webhook handlers, and other automation run as a specific cloud agent. The key is bound to one agent at creation time and inherits that agent's secrets and skills for every run. -## Service accounts and agent identities +See [API keys](/reference/cli/api-keys/) for the full creation flow and the differences between personal and agent keys. -"Agent identity" is the user-facing name for what Warp's CLI and REST API internally model as a **service account**. The two terms refer to the same underlying record: +## Service accounts -* When `oz whoami` reports a principal of `service_account:`, that principal is an agent identity on your team. -* When [`oz federate issue-token`](/reference/cli/federate/) emits a subject component like `service_account:my-sa-id`, the value identifies the agent identity the run is executing as. +In the CLI and REST API, a cloud agent is internally modeled as a **service account**. When `oz whoami` reports a principal like `service_account:`, or [`oz federate issue-token`](/reference/cli/federate/) emits a subject like `service_account:my-sa-id`, that principal is a cloud agent on your team. Use the agent picker in the UI or pass its UID to the API — the CLI surfaces the corresponding `service_account:` principal. -You don't need to distinguish the two terms in day-to-day use. Pick the agent identity in the UI or pass its UID to the API, and the CLI surfaces the corresponding `service_account:` principal. +## When to add more cloud agents -## Supporting multiple agent identities +Most teams start with one shared bot and add more as automation matures. Adding a new agent is worth it when distinct workflows have meaningfully different scopes — for example, a `ci-runner` that only needs read-only repo access, an `on-call` agent that holds production deploy credentials and is restricted to incident playbooks, and a `nightly-jobs` agent for scheduled cleanups. -Most teams start with the default agent identity and add more as their automation matures. Creating additional agent identities is worth it when distinct workflows have meaningfully different scopes — for example, a `ci-runner` identity that only needs read-only repo access, an `on-call` identity that holds production deploy credentials and is restricted to incident playbooks, and a `nightly-jobs` identity used by scheduled cleanups. - -Scoping each identity to a single workflow gives every run the minimum credentials it needs, keeps audit trails attributable to the right bot, and lets you revoke or rotate one workflow's access without touching the rest. +Scoping each agent to a single workflow gives every run the minimum credentials it needs, keeps audit trails clean, and lets you revoke or rotate one workflow's access without touching the rest. ## Plan limits -Every team starts with a default agent identity. Additional identities are subject to plan-based limits. See [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan. +Every team starts with a default cloud agent. Additional agents are subject to plan-based limits. See [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan. -When a team is over its plan limit (for example, after downgrading), the extra identities remain visible in the list but are marked as unavailable. Unavailable identities cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited. +When a team is over its plan limit (for example, after downgrading), the extra agents remain visible in the list but are marked as unavailable. Unavailable agents cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited. -## Managing agent identities +## Managing cloud agents -You can create, list, update, and delete agent identities 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. +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. - -## Running as an agent identity +* **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. -There are two ways to run a cloud agent as a specific agent identity: +## Running as a cloud agent -* **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. -* **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. +There are two ways to run a task as a specific cloud agent: -When neither path is used, automated runs (agent API key runs without an explicit override) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. +* **Authenticate with a key bound to the agent** — Every run started with that key executes as the bound agent. This is the typical path for CI pipelines and scheduled work. +* **Pass `agent_identity_uid` on `POST /agent/runs`** — For one-off runs, send the agent's `uid` in the request body. The field is only valid for team-owned runs. -## Where agent identities appear in the product +When neither path is used, automated runs use the team's default cloud agent. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. -Agent identities surface across several Oz surfaces: +## Where cloud agents appear in the product -* **Agents page** - The Agents page in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) is where teams view, create, edit, and delete agent identities. The same page lists the skills available to your team. -* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default option (runs execute as the calling user); selecting an agent identity runs as that identity instead. -* **Run filters and detail** - The Runs view lets you filter by agent identity, and individual run detail pages show which identity executed the run. -* **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by agent identity runs to the team rather than to a person. +* **Agents page** - The Agents page in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) is where teams view, create, edit, and delete cloud agents. The same page lists the skills available to your team. +* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default (runs execute as the calling user); picking a cloud agent runs as that bot instead. +* **Run filters and detail** - The Runs view lets you filter by cloud agent, and individual run detail pages show which agent executed the run. +* **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by agent runs to the team rather than to a person. ## Related pages -* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) - Manage the team-managed secrets you can attach to an agent identity. -* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use an agent identity for automation versus a personal identity. -* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the agent identity endpoints. -* [API keys](/reference/cli/api-keys/) - Create keys bound to a specific agent identity. -* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as an agent identity. -* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage agent identities and inspect their runs. +* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) - Manage the team-managed secrets you can attach to a cloud agent. +* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use a cloud agent for automation versus a personal identity. +* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the cloud agent endpoints. +* [API keys](/reference/cli/api-keys/) - Create keys bound to a specific cloud agent. +* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as a cloud agent. +* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage cloud agents and inspect their runs. * [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 77f78b44..b9df32e2 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -41,7 +41,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an [agent key](/agent-platform/cloud-agents/agents/) for automated runs (no specific user behind them). See [API keys](/reference/cli/api-keys/) for when to pick each. +* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to attribute runs to a [cloud agent](/agent-platform/cloud-agents/agents/) like `pr-reviewer`. See [API keys](/reference/cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx index 7d8a13df..e7e4ef7c 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx @@ -13,7 +13,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key bound to an [agent identity](/agent-platform/cloud-agents/agents/) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) for automated runs. See [API Keys](/reference/cli/api-keys/) for the full creation flow and principal selection. +* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key bound to a [cloud agent](/agent-platform/cloud-agents/agents/) (e.g., `pr-reviewer`) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/reference/cli/api-keys/) for the full creation flow. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx index dfce4d34..555410e9 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx @@ -39,7 +39,7 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx index cf284ee4..e4af4e5d 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx @@ -26,7 +26,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx index a00fdc1c..5c045f12 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx @@ -38,7 +38,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx index 104c6da8..9d1b21a9 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx @@ -19,7 +19,7 @@ This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/ * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` for self-hosting, or to a custom [agent identity](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index 08d03387..d0ea6715 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -33,7 +33,7 @@ No Docker, no worker daemon, no environment required — just the Oz CLI on any ### Prerequisites * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings) bound to the `Default Service Account` (or a custom [agent identity](/agent-platform/cloud-agents/agents/) so runs are attributed to a specific bot). See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. +* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings). Use the team's default, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index aa2923dc..5842f8bb 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -140,7 +140,7 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use an agent API key.** Tasks initiated with an agent API key bound to any [agent identity](/agent-platform/cloud-agents/agents/) on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Oz by Warp GitHub App rather than any individual user; in the Oz dashboard, the run is attributed to the bound agent identity (or to the `Default Service Account` for legacy team keys). +3. **Use an agent API key.** Tasks initiated with an agent API key on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Oz by Warp GitHub App rather than any individual user; in the Oz dashboard, the run is attributed to the bound [cloud agent](/agent-platform/cloud-agents/agents/). ### How this relates to environments @@ -156,7 +156,7 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm Team GitHub authorization is complementary to the existing personal token flow: * **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. -* **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Oz by Warp GitHub App rather than any individual user. In the Oz dashboard, the run is attributed to the bound [agent identity](/agent-platform/cloud-agents/agents/) (the `Default Service Account` for legacy team keys), which controls run filtering and audit attribution on the Warp side. +* **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Oz by Warp GitHub App rather than any individual user. In the Oz dashboard, the run is attributed to the bound [cloud agent](/agent-platform/cloud-agents/agents/), which controls run filtering and audit attribution on the Warp side. Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with an agent API key. diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index aac13682..86fe31ff 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -17,7 +17,7 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe ## Prerequisites -* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) and copy the raw value. Use a personal key if you want runs attributed to you, or an [agent key](/agent-platform/cloud-agents/agents/) for automated runs (no specific user behind them). See [API Keys](/reference/cli/api-keys/) for the full flow. +* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/agent-platform/cloud-agents/agents/). See [API Keys](/reference/cli/api-keys/) for the full flow. * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) first. --- diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index 461e58dd..0052e7c1 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -101,7 +101,7 @@ This error includes extra fields beyond the standard response format: 2. Ensure the app has access to all repositories listed in `inaccessible_repos`. 3. Retry the task. -If you are using an **agent API key** bound to an [agent identity](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. +If you are using an **agent API key** bound to a [cloud agent](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. ### Account matching failed diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 90555a55..d650af4c 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -8,36 +8,24 @@ sidebar: API keys let the Oz CLI and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. -## Principals: personal or agent +## Personal vs. agent keys -Every API key authenticates as a **principal** — either you (the human) or an [agent identity](/agent-platform/cloud-agents/agents/) (a team-scoped bot account). The choice of principal determines who runs are attributed to, which credentials they inherit, and how billing is charged. Pick the principal that matches the workflow, then create the key. +Every API key is either **personal** or **agent**, and the choice determines who the run is attributed to. -* **Personal API keys** authenticate as you. Runs execute with your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agent-platform/capabilities/skills/). Use a personal key when the automated workflow should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys. -* **Agent API keys** authenticate as a specific [agent identity](/agent-platform/cloud-agents/agents/) on your team. The key is bound to one identity at creation time. Runs inherit that identity's name, managed secrets, and skills, and show up in the [Oz dashboard](https://oz.warp.dev) attributed to that bot rather than to a person. +* **Personal API keys** authenticate as you. Runs use your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agent-platform/capabilities/skills/). Use a personal key when the run should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys. +* **Agent API keys** authenticate as a specific [cloud agent](/agent-platform/cloud-agents/agents/) on your team — a named bot like `deploy-bot` or `pr-reviewer`. Runs inherit the agent's secrets and skills, and show up in the [Oz dashboard](https://oz.warp.dev) attributed to that bot. Use an agent key for CI, scheduled jobs, and other automation you want attributed to a workflow rather than a person. -## Agent identities power agent API keys +## Cloud agents power agent API keys -An agent identity is a named bot account that your whole team can share. Each identity carries: +Each agent key is bound to one cloud agent at creation time. That agent carries: * **A name** — like `deploy-bot`, `pr-reviewer`, or `nightly-jobs`. Visible in the Agent picker, in run filters, and on every run that executes as it. -* **A description** — a short summary teammates see when picking the identity. -* **Managed secrets** — references (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to. A `deploy-bot` identity can hold `DEPLOY_TOKEN` and `DATABASE_URL`; a `pr-reviewer` identity doesn't see them. -* **Skills** — [skill specs](/agent-platform/capabilities/skills/) (e.g., `org/repo:.claude/skills/deploy/SKILL.md`) the identity comes preloaded with, so every run starts with the right instructions. -* **Plan-limit availability** — how many identities a team can use depends on the plan. See [Agent identities](/agent-platform/cloud-agents/agents/#plan-limits). +* **Managed secrets** — [team-managed secrets](/agent-platform/cloud-agents/secrets/) the agent should have access to. `deploy-bot` can hold `DEPLOY_TOKEN`; `pr-reviewer` doesn't see it. +* **Skills** — [skill specs](/agent-platform/capabilities/skills/) the agent comes preloaded with, so every run starts with the right instructions. -The payoff of binding an agent API key to a specific identity is **scoped automation**: the `deploy-bot` key can deploy because it inherits `DEPLOY_TOKEN`; the `pr-reviewer` key cannot, because its identity doesn't have the secret. Credentials and behavior are isolated per workflow, runs in the dashboard are filterable by which bot ran them, and you can rotate or revoke one workflow's access without touching the rest. +Binding a key to a specific cloud agent gives you **scoped automation**: the `deploy-bot` key can deploy because it inherits `DEPLOY_TOKEN`; the `pr-reviewer` key cannot. Runs in the dashboard are filterable by agent, and you can rotate or revoke one workflow's access without touching the rest. -See [Agent identities](/agent-platform/cloud-agents/agents/) for the full model — creating identities, attaching secrets and skills, and managing them via the public API. - -## The Default Service Account - -Every team starts with a built-in agent identity called `Default Service Account`. It's the no-config baseline: it has no attached secrets or skills, and automated runs that don't pick a specific identity execute as it. - -An agent API key bound to the `Default Service Account` is the simplest case of an agent key — it works for most teams that just want a single shared bot for automation. As you add named identities for specific workflows, the default keeps serving as the catch-all for runs that don't pick one. - -:::note -**Legacy "team API key" terminology.** Older docs, older Warp client versions, and some onboarding materials refer to what is now an agent API key bound to the `Default Service Account` as a "team API key." The two are the same key — the rename reflects that agent identities are now a first-class concept, not just a single auto-created service account. If your Warp desktop app's API key dialog still labels the toggle **Team**, picking it creates an agent API key bound to the `Default Service Account`. -::: +See [Cloud agents](/agent-platform/cloud-agents/agents/) for how to create and manage them. ## Creating an API key @@ -45,25 +33,25 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting ### From the Oz web app (recommended) -The Oz web app is the only surface where you can bind a key to a specific agent identity. If you want a key for a specific bot (e.g., `deploy-bot`), [create the identity](/agent-platform/cloud-agents/agents/) first. +The Oz web app is the only surface where you can bind an agent key to a specific cloud agent. If you want a key for a particular bot (e.g., `deploy-bot`), [create the agent](/agent-platform/cloud-agents/agents/) first. 1. Open [oz.warp.dev/settings](https://oz.warp.dev/settings). 2. In the API Keys section, click **New API key**. 3. Choose the principal: * **Personal** — Tied to your individual Warp account. - * **Agent** — Tied to a specific agent identity on your team. Pick an identity from the dropdown. The list always includes the `Default Service Account` and any custom identities the team has created. + * **Agent** — Tied to a specific cloud agent on your team. Pick one from the dropdown. 4. Enter a name for the key and choose an expiration (1 day, 30 days, 90 days, or never). 5. Click **Create key**. 6. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** ### From the Warp desktop app -The Warp desktop app binds agent keys to the `Default Service Account` automatically — it does not expose the named-identity picker. To bind a key to a custom identity, use the Oz web app instead. +The Warp desktop app produces personal keys and one shared agent key for the whole team. To bind a key to a specific cloud agent like `deploy-bot`, use the Oz web app instead. 1. In the Warp app, click your profile photo in the top-right corner, then click **Settings**. 2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. 3. In the API Keys section, click **+ Create API Key**. -4. Pick **Personal** for a personal key, or **Agent** / **Team** for an agent key bound to your team's `Default Service Account`. +4. Pick **Personal** for a personal key, or **Agent** / **Team** for an agent key tied to your team. (The toggle may still read **Team** in older versions of the desktop app.) 5. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). 6. Click **Create key**. 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** @@ -75,17 +63,17 @@ The Warp desktop app binds agent keys to the `Default Service Account` automatic ## Billing and GitHub authorization -How a run is billed and which GitHub permissions it gets are determined by the principal the key authenticates as. +How a run is billed and which GitHub permissions it gets depend on the type of key. -**Personal keys.** Runs execute as you, with your GitHub permissions and your account's credit pool. On Build, Max, and Business plans, the 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, per your Enterprise contract terms. Code changes are attributed to your GitHub account. +**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. -**Agent keys.** Runs execute as the bound agent identity, which is team-scoped. 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: agent identities authenticate via the **Oz by Warp** GitHub App when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured — commits and pull requests are opened by the GitHub App's bot user on GitHub, and the Oz dashboard attributes the run to the bound agent identity (the `Default Service Account` for legacy team keys). Without team GitHub authorization, agent keys can still run agents that don't need to write to GitHub (analysis, monitoring, triage). +**Agent keys.** Runs execute as the bound cloud agent, which is team-scoped. 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's bot user, and the Oz dashboard attributes the run to the bound cloud agent. Without team GitHub authorization, agent keys can still run tasks that don't need to write to GitHub (analysis, monitoring, triage). -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/). ## Authenticating with API keys -You can authenticate with an API key in the CLI using either an environment variable or a command flag. We recommend environment variables for security and easier reuse across multiple commands. +You can authenticate with an API key in the CLI using either an environment variable or a command flag. Environment variables are recommended for security and easier reuse across multiple commands. **Via environment variable (recommended):** @@ -110,7 +98,7 @@ The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the W * **Name** — The name you assigned when creating the key. * **Key** — A masked suffix (`wk-**xxxx`) to help identify the key. -* **Scope** — The principal the key authenticates as. Personal keys show your user; agent keys show the agent identity the key is bound to (the `Default Service Account` for legacy team keys, or whichever named identity you picked). Legacy keys may display as **Team** in the Warp desktop app. +* **Scope** — Personal keys show your user; agent keys show the cloud agent the key is bound to. * **Created** — When the key was created. * **Last used** — When the key was last used for authentication. * **Expires at** — The key's expiration date, or "Never" if it doesn't expire. @@ -122,15 +110,15 @@ To delete an API key, find it in either the Oz web app or the Warp desktop app's Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access. :::caution -Deleting a named [agent identity](/agent-platform/cloud-agents/agents/) atomically deletes every agent API key bound to that identity. To rotate the identity instead of removing it, generate a new key first, swap your automation over, and then delete the old key. +Deleting a [cloud agent](/agent-platform/cloud-agents/agents/) atomically deletes every agent API key bound to it. To rotate the agent instead of removing it, generate a new key first, swap your automation over, and then delete the old key. ::: ## Best practices -* **Pick the agent identity that matches the workflow** — Instead of using one shared `Default Service Account` key everywhere, create a custom identity per workflow (deploy bot, PR reviewer, dependency upgrader) and bind one key to each. Runs become filterable by identity, credentials stay scoped to the workflow that needs them, and rotation only affects the one workflow. -* **Use personal keys for personal-attribution workflows** — When an automated run should act on your behalf and code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys when the run is automation that runs without a specific person behind it. -* **Use environment variables** — Avoid passing API keys directly in commands where they may be logged or visible in shell history. -* **Set appropriate expiration** — Use shorter expiration times for development and testing; consider longer durations for stable production workflows. -* **Configure team GitHub authorization for agents that write to GitHub** — Personal keys authenticate as you with your GitHub permissions. Agent keys authenticate via the [Oz by Warp GitHub App](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) when team GitHub authorization is configured in the Admin Panel. -* **Rotate keys periodically** — Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. -* **Store securely** — Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. +* **Pick a cloud agent that matches the workflow.** Instead of using one shared key everywhere, create a cloud agent per workflow (deploy bot, PR reviewer, dependency upgrader) and bind one key to each. Runs become filterable by agent, credentials stay scoped to the workflow that needs them, and rotation only affects the one workflow. +* **Use personal keys when the run should act as you.** When code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys for automation you want attributed to a bot instead. +* **Use environment variables.** Avoid passing API keys directly in commands where they may be logged or visible in shell history. +* **Set appropriate expiration.** Use shorter expiration times for development and testing; consider longer durations for stable production workflows. +* **Configure team GitHub authorization for agents that write to GitHub.** Personal keys authenticate as you with your GitHub permissions. Agent keys authenticate via the [Oz by Warp GitHub App](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) when team GitHub authorization is configured in the Admin Panel. +* **Rotate keys periodically.** Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. +* **Store securely.** Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. From 0e9da2ce845ab8189437fe04c43d242db36785cf Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 01:01:14 +0000 Subject: [PATCH 09/12] 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 --- .../agent-platform/cloud-agents/agents.mdx | 102 +++++------------- .../integrations/github-actions.mdx | 2 +- .../quickstart-github-actions.mdx | 2 +- .../self-hosting/managed-direct.mdx | 2 +- .../self-hosting/managed-docker.mdx | 2 +- .../self-hosting/managed-kubernetes.mdx | 2 +- .../cloud-agents/self-hosting/quickstart.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 2 +- src/content/docs/reference/cli/api-keys.mdx | 33 ++---- 9 files changed, 38 insertions(+), 111 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 634be918..3516ed28 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -1,84 +1,35 @@ --- title: Agents description: >- - Cloud agents are team-scoped bots that run automation in Oz. Create - named agents per workflow to separate credentials, preload skills, and - attribute runs. + Cloud agents are how Warp runs scheduled jobs, integration triggers, CI/CD + automation, and API-driven tasks against your team's environments. sidebar: label: "Agents" --- -A **cloud agent** is a named bot your team can share. It has its own credentials and skills, and any run it executes shows up in the dashboard attributed to that bot rather than to a person. Bind an [API key](/reference/cli/api-keys/) to one and CI pipelines, scheduled jobs, and webhooks can all act as that bot. +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. -Create a named agent per workflow when you want to: +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. -* **Separate workflows.** A `deploy-bot` for production deploys, a `dependabot-runner` for nightly upgrades, a `pr-reviewer` for inline code review. Runs are filterable by agent in the [Oz dashboard](https://oz.warp.dev/runs), and each run page shows which bot did the work. -* **Scope credentials.** Attach managed secrets to one agent so only its runs receive them. `deploy-bot` can hold `DEPLOY_TOKEN` and `DATABASE_URL` for production deploys; `pr-reviewer` doesn't see either, because its runs never need to deploy. -* **Preload skills.** Attach [skill specs](/agent-platform/capabilities/skills/) to an agent so every run starts with the right instructions. A `pr-reviewer` preloaded with `org/repo:.warp/skills/code-review/SKILL.md` doesn't need `--skill` on every invocation. -* **Attribute automated work.** CI pipelines, webhooks, and scheduled jobs authenticated by an agent's API key show up in run history as that bot, not as a teammate. Audit trails stay attributable to the workflow, not the person who happened to set up the key. +## How cloud agents get triggered -## What you can configure +Cloud agents are characterized by what triggers them. Common triggers: -Each cloud agent has: +* **Schedules** — Cron-style recurring runs. See [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). +* **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. +* **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. +* **Warp app** — `/cloud-agent` and Cloud Mode in the Warp desktop app. -* **Name** — Like `deploy-bot`, `pr-reviewer`, or `nightly-jobs`. Visible in the Agent picker, in run filters, and on every run that executes as it. -* **Description** — A short summary teammates see when picking the agent. -* **Managed secrets** — References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the agent should have access to. -* **Skills** — Skill specs (for example, `org/repo:path/to/SKILL.md`) the agent comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. - -## Quickstart: create a custom cloud agent - -This walkthrough creates a `deploy-bot` agent, gives it a deploy secret and a deploy skill, generates an API key bound to it, and uses that key to trigger a run that shows up in the dashboard attributed to `deploy-bot`. - -1. **Create a managed secret** the agent will need (skip if your team already has one). In the [Oz web app](https://oz.warp.dev/secrets), add a `DEPLOY_TOKEN` team-scoped secret. See [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) for the full secret-management flow. -2. **Create the cloud agent.** Send a `POST` to `/api/v1/agent/identities` with your existing API key (or use the Agents page at [oz.warp.dev/agents](https://oz.warp.dev/agents) once it's wired up to a UI): - - ```bash - curl -X POST https://app.warp.dev/api/v1/agent/identities \ - -H "Authorization: Bearer $WARP_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "deploy-bot", - "description": "Handles production deploys off main.", - "secrets": [{"name": "DEPLOY_TOKEN"}], - "skills": ["warpdotdev/warp-server:.claude/skills/deploy/SKILL.md"] - }' - ``` - - **Expected outcome:** A `201 Created` response with the new agent's `uid`, `name`, and `available: true`. -3. **Generate an API key bound to the agent.** In [oz.warp.dev/settings](https://oz.warp.dev/settings), click **New API key**, pick **Agent**, select `deploy-bot` from the dropdown, name the key, and copy the raw value. See [API keys](/reference/cli/api-keys/) for the full creation flow. -4. **Use the key to run an agent.** Export the key and trigger a run — the agent will have `DEPLOY_TOKEN` injected automatically and the `deploy` skill preloaded: - - ```bash - export WARP_API_KEY="wk-..." - oz agent run-cloud --environment --prompt "Deploy the latest main to production" - ``` - -5. **Confirm attribution.** Open the [Oz dashboard](https://oz.warp.dev/runs) and filter by agent. The run shows up under `deploy-bot`, not under your user account. - -The same pattern works for any per-workflow bot: a `pr-reviewer` with read-only GitHub access and a code-review skill, a `nightly-jobs` agent used by scheduled cleanups, an `on-call` agent that holds incident-playbook skills and production credentials. +Each run is tracked in the [Oz dashboard](https://oz.warp.dev/runs) with its trigger source, the environment it ran in, and the full transcript. ## Agent API keys -An **agent API key** is the credential that lets CI, schedulers, webhook handlers, and other automation run as a specific cloud agent. The key is bound to one agent at creation time and inherits that agent's secrets and skills for every run. - -See [API keys](/reference/cli/api-keys/) for the full creation flow and the differences between personal and agent keys. +Most automation triggers authenticate using an **agent API key** — a credential that runs as a cloud agent on your team rather than as an individual user. See [API keys](/reference/cli/api-keys/) for how personal and agent keys differ, and how to create one. ## Service accounts -In the CLI and REST API, a cloud agent is internally modeled as a **service account**. When `oz whoami` reports a principal like `service_account:`, or [`oz federate issue-token`](/reference/cli/federate/) emits a subject like `service_account:my-sa-id`, that principal is a cloud agent on your team. Use the agent picker in the UI or pass its UID to the API — the CLI surfaces the corresponding `service_account:` principal. - -## When to add more cloud agents - -Most teams start with one shared bot and add more as automation matures. Adding a new agent is worth it when distinct workflows have meaningfully different scopes — for example, a `ci-runner` that only needs read-only repo access, an `on-call` agent that holds production deploy credentials and is restricted to incident playbooks, and a `nightly-jobs` agent for scheduled cleanups. - -Scoping each agent to a single workflow gives every run the minimum credentials it needs, keeps audit trails clean, and lets you revoke or rotate one workflow's access without touching the rest. - -## Plan limits - -Every team starts with a default cloud agent. Additional agents are subject to plan-based limits. See [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan. - -When a team is over its plan limit (for example, after downgrading), the extra agents remain visible in the list but are marked as unavailable. Unavailable agents cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited. +In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:` when the CLI is authenticated as one, and [`oz federate issue-token`](/reference/cli/federate/) emits the same form in OIDC token subjects. ## Managing cloud agents @@ -99,28 +50,25 @@ A few constraints apply across every endpoint: * **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. -## Running as a cloud agent - -There are two ways to run a task as a specific cloud agent: +## Plan limits -* **Authenticate with a key bound to the agent** — Every run started with that key executes as the bound agent. This is the typical path for CI pipelines and scheduled work. -* **Pass `agent_identity_uid` on `POST /agent/runs`** — For one-off runs, send the agent's `uid` in the request body. The field is only valid for team-owned runs. +Every team starts with a default cloud agent. Additional agents are subject to plan-based limits. See [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan. -When neither path is used, automated runs use the team's default cloud agent. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app. +When a team is over its plan limit (for example, after downgrading), the extra agents remain visible in the list but are marked as unavailable. Unavailable agents cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited. ## Where cloud agents appear in the product -* **Agents page** - The Agents page in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) is where teams view, create, edit, and delete cloud agents. The same page lists the skills available to your team. -* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default (runs execute as the calling user); picking a cloud agent runs as that bot instead. +* **Agents page** - The Agents page in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) is where teams view, create, edit, and delete cloud agents. +* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default (runs execute as the calling user); picking a cloud agent runs as the cloud agent instead. * **Run filters and detail** - The Runs view lets you filter by cloud agent, and individual run detail pages show which agent executed the run. -* **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by agent runs to the team rather than to a person. +* **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by cloud agent runs to the team rather than to a person. ## Related pages -* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) - Manage the team-managed secrets you can attach to a cloud agent. -* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use a cloud agent for automation versus a personal identity. +* [Triggers](/agent-platform/cloud-agents/triggers/) - How schedules, integrations, and API calls invoke cloud agents. +* [Environments](/agent-platform/cloud-agents/environments/) - The runtime context (Docker image, repos, setup commands) a cloud agent uses. +* [API keys](/reference/cli/api-keys/) - Create personal and agent API keys. * [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the cloud agent endpoints. -* [API keys](/reference/cli/api-keys/) - Create keys bound to a specific cloud agent. -* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as a cloud agent. -* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage cloud agents and inspect their runs. +* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run. +* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - Manage cloud agents and inspect their runs in the web UI. * [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index b9df32e2..a7444729 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -41,7 +41,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to attribute runs to a [cloud agent](/agent-platform/cloud-agents/agents/) like `pr-reviewer`. See [API keys](/reference/cli/api-keys/) for when to pick each. +* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/agent-platform/cloud-agents/agents/) on your team. See [API keys](/reference/cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx index e7e4ef7c..9271b264 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx @@ -13,7 +13,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key bound to a [cloud agent](/agent-platform/cloud-agents/agents/) (e.g., `pr-reviewer`) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). Use a personal key if the agent should commit as you, or an agent key (which runs as a [cloud agent](/agent-platform/cloud-agents/agents/) on your team) with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/reference/cli/api-keys/) for the full creation flow. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx index 555410e9..3b493bd9 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-direct.mdx @@ -39,7 +39,7 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **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. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx index e4af4e5d..0e2e7eac 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-docker.mdx @@ -26,7 +26,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **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. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx index 5c045f12..7582042f 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/managed-kubernetes.mdx @@ -38,7 +38,7 @@ This page covers the [managed architecture](/agent-platform/cloud-agents/self-ho * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **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. --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx index 9d1b21a9..d13ac391 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx @@ -19,7 +19,7 @@ This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/ * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **An agent API key** — Create one in the [Oz web app](https://oz.warp.dev/settings). Use the team's default for self-hosting, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the worker's runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **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. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). --- diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index d0ea6715..8b0c1fe6 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -33,7 +33,7 @@ No Docker, no worker daemon, no environment required — just the Oz CLI on any ### Prerequisites * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings). Use the team's default, or bind it to a custom [cloud agent](/agent-platform/cloud-agents/agents/) if you want the runs attributed to a named bot. See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. +* **A Warp API key** — For automation, create an agent API key in the [Oz web app](https://oz.warp.dev/settings). See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index d650af4c..8fd3a60e 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -10,22 +10,10 @@ API keys let the Oz CLI and cloud agents authenticate without human interaction. ## Personal vs. agent keys -Every API key is either **personal** or **agent**, and the choice determines who the run is attributed to. +Every API key is either **personal** or **agent**. * **Personal API keys** authenticate as you. Runs use your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agent-platform/capabilities/skills/). Use a personal key when the run should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys. -* **Agent API keys** authenticate as a specific [cloud agent](/agent-platform/cloud-agents/agents/) on your team — a named bot like `deploy-bot` or `pr-reviewer`. Runs inherit the agent's secrets and skills, and show up in the [Oz dashboard](https://oz.warp.dev) attributed to that bot. Use an agent key for CI, scheduled jobs, and other automation you want attributed to a workflow rather than a person. - -## Cloud agents power agent API keys - -Each agent key is bound to one cloud agent at creation time. That agent carries: - -* **A name** — like `deploy-bot`, `pr-reviewer`, or `nightly-jobs`. Visible in the Agent picker, in run filters, and on every run that executes as it. -* **Managed secrets** — [team-managed secrets](/agent-platform/cloud-agents/secrets/) the agent should have access to. `deploy-bot` can hold `DEPLOY_TOKEN`; `pr-reviewer` doesn't see it. -* **Skills** — [skill specs](/agent-platform/capabilities/skills/) the agent comes preloaded with, so every run starts with the right instructions. - -Binding a key to a specific cloud agent gives you **scoped automation**: the `deploy-bot` key can deploy because it inherits `DEPLOY_TOKEN`; the `pr-reviewer` key cannot. Runs in the dashboard are filterable by agent, and you can rotate or revoke one workflow's access without touching the rest. - -See [Cloud agents](/agent-platform/cloud-agents/agents/) for how to create and manage them. +* **Agent API keys** run as a [cloud agent](/agent-platform/cloud-agents/agents/) on your team. Use an agent key for scheduled jobs, integrations (Slack, Linear, GitHub Actions), SDK-triggered runs, and other automation that isn't tied to a specific user. Billing and GitHub permissions are scoped to the team rather than to you. ## Creating an API key @@ -33,21 +21,17 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting ### From the Oz web app (recommended) -The Oz web app is the only surface where you can bind an agent key to a specific cloud agent. If you want a key for a particular bot (e.g., `deploy-bot`), [create the agent](/agent-platform/cloud-agents/agents/) first. - 1. Open [oz.warp.dev/settings](https://oz.warp.dev/settings). 2. In the API Keys section, click **New API key**. 3. Choose the principal: * **Personal** — Tied to your individual Warp account. - * **Agent** — Tied to a specific cloud agent on your team. Pick one from the dropdown. + * **Agent** — Runs as a cloud agent on your team. Pick a cloud agent from the dropdown. 4. Enter a name for the key and choose an expiration (1 day, 30 days, 90 days, or never). 5. Click **Create key**. 6. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** ### From the Warp desktop app -The Warp desktop app produces personal keys and one shared agent key for the whole team. To bind a key to a specific cloud agent like `deploy-bot`, use the Oz web app instead. - 1. In the Warp app, click your profile photo in the top-right corner, then click **Settings**. 2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. 3. In the API Keys section, click **+ Create API Key**. @@ -67,7 +51,7 @@ How a run is billed and which GitHub permissions it gets depend on the type of k **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. -**Agent keys.** Runs execute as the bound cloud agent, which is team-scoped. 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's bot user, and the Oz dashboard attributes the run to the bound cloud agent. Without team GitHub authorization, agent keys can still run tasks that don't need to write to GitHub (analysis, monitoring, triage). +**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). 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/). @@ -98,7 +82,7 @@ The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the W * **Name** — The name you assigned when creating the key. * **Key** — A masked suffix (`wk-**xxxx`) to help identify the key. -* **Scope** — Personal keys show your user; agent keys show the cloud agent the key is bound to. +* **Scope** — Personal keys show your user; agent keys show the cloud agent the key runs as. * **Created** — When the key was created. * **Last used** — When the key was last used for authentication. * **Expires at** — The key's expiration date, or "Never" if it doesn't expire. @@ -109,14 +93,9 @@ To delete an API key, find it in either the Oz web app or the Warp desktop app's Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access. -:::caution -Deleting a [cloud agent](/agent-platform/cloud-agents/agents/) atomically deletes every agent API key bound to it. To rotate the agent instead of removing it, generate a new key first, swap your automation over, and then delete the old key. -::: - ## Best practices -* **Pick a cloud agent that matches the workflow.** Instead of using one shared key everywhere, create a cloud agent per workflow (deploy bot, PR reviewer, dependency upgrader) and bind one key to each. Runs become filterable by agent, credentials stay scoped to the workflow that needs them, and rotation only affects the one workflow. -* **Use personal keys when the run should act as you.** When code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys for automation you want attributed to a bot instead. +* **Use personal keys for runs that should act as you.** When code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys for automation that isn't tied to a specific user. * **Use environment variables.** Avoid passing API keys directly in commands where they may be logged or visible in shell history. * **Set appropriate expiration.** Use shorter expiration times for development and testing; consider longer durations for stable production workflows. * **Configure team GitHub authorization for agents that write to GitHub.** Personal keys authenticate as you with your GitHub permissions. Agent keys authenticate via the [Oz by Warp GitHub App](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) when team GitHub authorization is configured in the Admin Panel. From fbba1449df8777917b4d6ad555a3a93e7cf13c44 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 27 May 2026 09:25:57 -0700 Subject: [PATCH 10/12] Update src/content/docs/agent-platform/cloud-agents/agents.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> --- src/content/docs/agent-platform/cloud-agents/agents.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 3516ed28..b597df93 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -16,7 +16,7 @@ Every team starts with a default cloud agent, which is what runs when an automat Cloud agents are characterized by what triggers them. Common triggers: * **Schedules** — Cron-style recurring runs. See [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). -* **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. +* **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. * **Warp app** — `/cloud-agent` and Cloud Mode in the Warp desktop app. From 7ffe967bcdbd2399ae6a546e4c91ce48f111f6c7 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 17:20:37 +0000 Subject: [PATCH 11/12] 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 --- .../agent-platform/cloud-agents/agents.mdx | 19 ++++------ .../cloud-agents/deployment-patterns.mdx | 2 +- .../agent-platform/cloud-agents/overview.mdx | 2 +- .../cloud-agents/oz-web-app.mdx | 4 +-- .../agent-platform/cloud-agents/secrets.mdx | 6 ++-- src/content/docs/reference/cli/api-keys.mdx | 35 ++++++++++++------- src/content/docs/reference/cli/federate.mdx | 2 +- src/content/docs/reference/cli/index.mdx | 2 +- src/sidebar.ts | 2 +- 9 files changed, 40 insertions(+), 34 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index b597df93..32ca459f 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -9,7 +9,7 @@ sidebar: 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. -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. ## How cloud agents get triggered @@ -18,8 +18,8 @@ Cloud agents are characterized by what triggers them. Common triggers: * **Schedules** — Cron-style recurring runs. See [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). * **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. -* **Warp app** — `/cloud-agent` and Cloud Mode in the Warp desktop app. +* **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 desktop app. See the [cloud agents quickstart](/agent-platform/cloud-agents/quickstart/). Each run is tracked in the [Oz dashboard](https://oz.warp.dev/runs) with its trigger source, the environment it ran in, and the full transcript. @@ -29,22 +29,17 @@ Most automation triggers authenticate using an **agent API key** — a credentia ## Service accounts -In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:` 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:` 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. ## Managing cloud agents -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. +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. -The endpoints behave as follows: - -* **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 agent and atomically deletes every API key bound to it. The team's default agent cannot be deleted. +
ActionEndpointWhat it does
CreatePOST /agent/identitiesCreates a cloud agent with a name and optional description, secrets, and skills.
ListGET /agent/identitiesReturns every cloud agent on the team, including the default, with an available flag for plan-limit status.
UpdatePUT /agent/identities/{uid}Replaces individual fields. Omitted fields stay unchanged; empty strings or arrays clear the field.
DeleteDELETE /agent/identities/{uid}Soft-deletes the agent and deletes every API key bound to it. The team's default agent cannot be deleted.
### Caller requirements -A few constraints apply across every endpoint: +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. diff --git a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx index 3c8d4e1e..a8fd99e0 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -53,7 +53,7 @@ Use this when you already have a system that schedules work (CI, dev boxes, inte #### Minimal setup checklist * A Warp team -* An [agent identity](/agent-platform/cloud-agents/agents/) (recommended for automation) +* A [cloud agent](/agent-platform/cloud-agents/agents/) (recommended for automation) * The Oz CLI installed on the runner / box * Any needed credentials (often via secrets + environment variables) diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx index a5608f05..9c7ec2f6 100644 --- a/src/content/docs/agent-platform/cloud-agents/overview.mdx +++ b/src/content/docs/agent-platform/cloud-agents/overview.mdx @@ -144,7 +144,7 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut * [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) — run your first cloud agent with an environment in ~10 minutes. * [Oz Platform](/agent-platform/cloud-agents/platform/) — CLI, Oz API/SDK, orchestration, tasks, environments, hosts, integrations, and more. * [Harnesses](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. -* [Agent identities](/agent-platform/cloud-agents/agents/) — team-scoped bot accounts that own and execute cloud agent runs. +* [Agents](/agent-platform/cloud-agents/agents/) — cloud agents that own and execute runs on your team. * [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) — coordinate a parent agent and its child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows. * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. * [Oz CLI](/reference/cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. diff --git a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx index f1efdd14..922697c3 100644 --- a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx +++ b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx @@ -95,7 +95,7 @@ The **Agents** page (`/agents`) is where you browse, create, and run saved agent Skills are reusable instruction sets stored in repositories. You can attach existing skills to an agent through the **Skills** field; for more details, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). -Saved agents use Warp's team-scoped identity model, which lets a reusable agent own runs and carry default configuration for teammates. You manage saved agents from the Agents page. For plan limits, API endpoints, and API key binding behavior, see [Agent identities](/agent-platform/cloud-agents/agents/). +Saved agents use Warp's team-scoped identity model, which lets a reusable agent own runs and carry default configuration for teammates. You manage saved agents from the Agents page. For plan limits, API endpoints, and API key binding behavior, see [Agents](/agent-platform/cloud-agents/agents/).
![The Agents page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-agents.png) @@ -116,7 +116,7 @@ To create a saved agent: 2. Define the instructions and defaults. Add a name, description, prompt, optional skills, harness, model, environment, and secrets. 3. Click **Create agent**. The saved agent appears on the Agents page and is available for runs. -For deeper guidance on reusable skills and team-scoped identities, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) and [Agent identities](/agent-platform/cloud-agents/agents/). +For deeper guidance on reusable skills and team-scoped identities, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) and [Agents](/agent-platform/cloud-agents/agents/).
![Creating a new agent in the Oz web app.](../../../../assets/agent-platform/oz-web-app-new-agent.png) diff --git a/src/content/docs/agent-platform/cloud-agents/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index 28e5622d..e9d3b8a8 100644 --- a/src/content/docs/agent-platform/cloud-agents/secrets.mdx +++ b/src/content/docs/agent-platform/cloud-agents/secrets.mdx @@ -57,7 +57,7 @@ Team secrets are shared across the entire team and are available to all cloud ag * Ideal for shared infrastructure credentials, service accounts, and read-only API keys :::note -Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. When you want a credential to be available to one workflow only, attach it to an [agent identity](/agent-platform/cloud-agents/agents/) instead of giving every run access to it. +Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. When you want a credential to be available to one workflow only, attach it to a [cloud agent](/agent-platform/cloud-agents/agents/) instead of giving every run access to it. ::: **For example:** @@ -69,7 +69,7 @@ Because team secrets are broadly available and may be used by fully automated or This ensures credentials remain valid as team membership changes, permissions are tightly scoped, and ownership and rotation align with internal security policies. :::note -Team secrets can also be attached directly to an [agent identity](/agent-platform/cloud-agents/agents/), so only runs executing as that identity receive them. The secret itself still lives in the team's secret scope; the agent identity only references it by name. +Team secrets can also be attached directly to a [cloud agent](/agent-platform/cloud-agents/agents/), so only runs executing as that cloud agent receive them. The secret itself still lives in the team's secret scope; the cloud agent only references it by name. ::: #### Personal secrets @@ -249,7 +249,7 @@ Personal secrets are never injected in these cases. ## Scoping secrets to environments and runs -Owner scoping (team versus personal) controls **which secrets exist** for a caller. Two additional layers — environments and individual runs — let you narrow **which of those secrets are actually injected** for a given execution. Together with [agent identities](/agent-platform/cloud-agents/agents/), these layers form a broader access-scoping model where each layer contributes the secrets a run ends up with at execution time. +Owner scoping (team versus personal) controls **which secrets exist** for a caller. Two additional layers — environments and individual runs — let you narrow **which of those secrets are actually injected** for a given execution. Together with [cloud agents](/agent-platform/cloud-agents/agents/), these layers form a broader access-scoping model where each layer contributes the secrets a run ends up with at execution time. ### Environment-level scoping diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 8fd3a60e..73faf9a5 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -10,27 +10,27 @@ API keys let the Oz CLI and cloud agents authenticate without human interaction. ## Personal vs. agent keys -Every API key is either **personal** or **agent**. +Every API key is either a **personal API key** or an **agent API key**. * **Personal API keys** authenticate as you. Runs use your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agent-platform/capabilities/skills/). Use a personal key when the run should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys. * **Agent API keys** run as a [cloud agent](/agent-platform/cloud-agents/agents/) on your team. Use an agent key for scheduled jobs, integrations (Slack, Linear, GitHub Actions), SDK-triggered runs, and other automation that isn't tied to a specific user. Billing and GitHub permissions are scoped to the team rather than to you. ## Creating an API key -You can create an API key in either the [Oz web app](https://oz.warp.dev/settings) or the Warp desktop app. Both surfaces produce keys that authenticate the CLI and SDK identically. +You can create an API key in either the [Oz web app](https://oz.warp.dev/settings) or the Warp app. Both surfaces produce keys that authenticate the CLI and SDK identically. ### From the Oz web app (recommended) 1. Open [oz.warp.dev/settings](https://oz.warp.dev/settings). -2. In the API Keys section, click **New API key**. -3. Choose the principal: +2. In the API keys section, click **Generate new token**. +3. Choose the type: * **Personal** — Tied to your individual Warp account. * **Agent** — Runs as a cloud agent on your team. Pick a cloud agent from the dropdown. 4. Enter a name for the key and choose an expiration (1 day, 30 days, 90 days, or never). 5. Click **Create key**. 6. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.** -### From the Warp desktop app +### From the Warp app 1. In the Warp app, click your profile photo in the top-right corner, then click **Settings**. 2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. @@ -45,13 +45,21 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting
API key management interface in Warp settings.
-## Billing and GitHub authorization +## How key type affects billing and GitHub access -How a run is billed and which GitHub permissions it gets depend on the type of key. +The key type determines who the run is attributed to, which credit pool is billed, and which GitHub credentials the agent can use. -**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** -**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). +* 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/). @@ -78,14 +86,17 @@ API keys start with the prefix `wk-`. If your key doesn't have this prefix, it m ## Managing API keys -The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the Warp app's **Settings** > **Cloud platform** > **Oz Cloud API Keys** both display your active keys with the following information: +The Oz web app at [oz.warp.dev/settings](https://oz.warp.dev/settings) and the Warp app's **Settings** > **Cloud platform** > **Oz Cloud API Keys** both list your active keys. Both surfaces show: * **Name** — The name you assigned when creating the key. -* **Key** — A masked suffix (`wk-**xxxx`) to help identify the key. * **Scope** — Personal keys show your user; agent keys show the cloud agent the key runs as. +* **Expires at** — The key's expiration date, or "Never" if it doesn't expire. + +The Warp app also shows additional metadata that isn't surfaced in the Oz web app: + +* **Key** — A masked suffix (`wk-**xxxx`) to help identify the key. * **Created** — When the key was created. * **Last used** — When the key was last used for authentication. -* **Expires at** — The key's expiration date, or "Never" if it doesn't expire. ### Deleting API keys diff --git a/src/content/docs/reference/cli/federate.mdx b/src/content/docs/reference/cli/federate.mdx index ecfcc9da..c8512464 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/reference/cli/federate.mdx @@ -44,7 +44,7 @@ oz federate issue-token \ The subject claim is what your cloud provider's policy will match on, so pick the combination that gives you the IAM granularity you need. Supported components: -* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`. A `service_account:` principal corresponds to an [agent identity](/agent-platform/cloud-agents/agents/) on your team. +* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`. A `service_account:` principal corresponds to a [cloud agent](/agent-platform/cloud-agents/agents/) on your team. * **`scoped_principal`** - The principal scoped to a team, like `principal:my-team-id/user:my-user-id`. * **`email`** - The principal's email, like `email:user@warp.dev`. * **`teams`** - The principal's team, like `teams:my-team-id`. diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index 569f82f2..8a9110ba 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -158,7 +158,7 @@ Use `oz whoami` to print information about the currently authenticated principal oz whoami ``` -The output includes your user or service account ID, display name, email, and team (when available). When the CLI is authenticated as a service account principal, that principal is an [agent identity](/agent-platform/cloud-agents/agents/) on your team. For machine-readable output, set `--output-format json` or `--output-format text`. +The output includes your user or service account ID, display name, email, and team (when available). When the CLI is authenticated as a service account principal, that principal is a [cloud agent](/agent-platform/cloud-agents/agents/) on your team. For machine-readable output, set `--output-format json` or `--output-format text`. ```sh # JSON output for scripts diff --git a/src/sidebar.ts b/src/sidebar.ts index ed8b12fd..ce540361 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -368,7 +368,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agent-platform/cloud-agents/orchestration/multi-agent-runs', label: 'Running orchestrated agents' }, ], }, - { slug: 'agent-platform/cloud-agents/agents', label: 'Agent identities' }, + { slug: 'agent-platform/cloud-agents/agents', label: 'Agents' }, { slug: 'agent-platform/cloud-agents/oz-web-app', label: 'Oz web app' }, { slug: 'agent-platform/cloud-agents/skills-as-agents', label: 'Skills as agents' }, { slug: 'agent-platform/cloud-agents/viewing-cloud-agent-runs', label: 'Viewing cloud agent runs' }, From f67e32deb4c09409d7c849bb609e1fda54d1a2b5 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 18:36:35 +0000 Subject: [PATCH 12/12] Use 'Warp app' consistently in two remaining spots MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- src/content/docs/agent-platform/cloud-agents/agents.mdx | 2 +- src/content/docs/reference/cli/api-keys.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 32ca459f..ff2c33fe 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -19,7 +19,7 @@ Cloud agents are characterized by what triggers them. Common triggers: * **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 desktop app. See the [cloud agents quickstart](/agent-platform/cloud-agents/quickstart/). +* **Warp app** — The `/cloud-agent` slash command in the Warp app. See the [cloud agents quickstart](/agent-platform/cloud-agents/quickstart/). Each run is tracked in the [Oz dashboard](https://oz.warp.dev/runs) with its trigger source, the environment it ran in, and the full transcript. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 73faf9a5..f520502c 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -100,7 +100,7 @@ The Warp app also shows additional metadata that isn't surfaced in the Oz web ap ### Deleting API keys -To delete an API key, find it in either the Oz web app or the Warp desktop app's API Keys list and click the delete icon next to the key. +To delete an API key, find it in either the Oz web app or the Warp app's API Keys list and click the delete icon next to the key. Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access.