warpdotdev · seemeroland · May 28, 2026
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
@@ -43,7 +43,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) — create an Agent API key for the [agent](/agent-platform/cloud-agents/agents/) that should run the workflow. Use a personal key only when the workflow needs to run with your individual Warp identity. Avoid legacy team keys for GitHub Actions workflows.
 * 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)
@@ -209,6 +209,22 @@ What it does:
 
 ## Troubleshooting
 
+### Authentication fails with a 401
+
+If the action fails with `Authentication failed` or `401 Unauthorized` while fetching user data, check the Warp API key used by the `warp_api_key` input:
+
+1. **Verify the secret value** - Confirm the GitHub Actions secret contains the full Warp API key, including the `wk-` prefix.
+2. **Use an Agent API key for team automation** - For GitHub Actions workflows that run as a team or named agent, create an Agent API key for the agent that should run the workflow. Legacy team keys may not authenticate correctly for new Oz automation flows.
+3. **Use a personal API key only for personal runs** - Personal keys run with your individual Warp identity and are appropriate when the workflow should act as you.
+
+After replacing the secret, rerun the failed GitHub Actions job.
+
+### Warp logs include bundled configuration values
+
+The action prints the Warp log path when a CLI command fails. Those logs can include client configuration metadata used by the packaged Oz CLI. Values with names like `firebase_auth_api_key`, RudderStack `write_key`, `ugc_write_key`, and GitHub OAuth `client_secret` are Warp-owned client configuration values, not secrets from your GitHub repository or Warp team.
+
+Recent Oz CLI versions redact these sensitive-looking channel configuration values when the channel state is written to `warp.log`. Continue to remove any real repository secrets, GitHub tokens, API keys, or environment variables before sharing logs externally.
+
 ### `@oz-agent` mention doesn't trigger the workflow
 
 If you're tagging `@oz-agent` in a PR or issue comment and the workflow doesn't run:

diff --git a/...ent/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/...ent/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx
@@ -13,12 +13,12 @@ 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 an Agent API key for the [agent](/agent-platform/cloud-agents/agents/) that should run the workflow, then store it as a GitHub Actions secret. Use a personal key only when the workflow needs to run with your individual Warp identity. Avoid legacy team keys for GitHub Actions 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.
 
 ---
 
-## 1. Add your API key as a GitHub Actions secret
+## Add your API key as a GitHub Actions secret
 
 Store your Warp API key as a GitHub Actions secret so workflows can authenticate without exposing the key in your code.
 
@@ -28,7 +28,7 @@ Store your Warp API key as a GitHub Actions secret so workflows can authenticate
 4. Paste your API key into the **Secret** field.
 5. Click **Add secret**.
 
-## 2. Create the workflow file
+## Create the workflow file
 
 This workflow triggers an agent whenever a PR is opened or marked ready for review. The agent reviews the diff and posts inline comments.
 
@@ -64,7 +64,7 @@ jobs:
 
 This workflow listens for pull request events and runs the `oz-agent-action` step, which executes the prompt to review code changes. Commit and push this file to your default branch to activate the workflow.
 
-## 3. Open a pull request
+## Open a pull request
 
 Create a new pull request in your repository to trigger the workflow.
 
@@ -74,7 +74,7 @@ To verify the workflow ran:
 2. Click **Oz PR review** in the list of workflows.
 3. Select the most recent run to see the agent's output in the job logs.
 
-## 4. View the run
+## View the run
 
 Each `oz-agent-action` step creates a cloud agent run you can inspect from the Oz dashboard:
 

diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx
@@ -18,35 +18,37 @@ You can create an API key from your settings in Warp:
 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
+   * `Agent` - Tied to a named agent for team automation
+   * `Team` - Legacy team-scoped key type. Prefer Agent API keys for new automation.
 
 :::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.
+* 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 not attributed to any individual user.
 :::
 
 :::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.
+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.
 :::
 
 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.**
 
-<figure>
+<figure style={{ maxWidth: "563px" }}>
 ![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png)
 <figcaption>API key management interface in Warp settings.</figcaption>
 </figure>
 
-## Personal vs team API keys
+## Personal, Agent, and Team API keys
 
-Warp supports two types of API keys, each with different billing and identity behavior:
+Warp supports these API key types, each with different billing and identity behavior:
 
 * **Personal API keys** - Cloud agent runs authenticate as you, just like running an agent from the Warp app or triggering one via Slack or Linear. On Build, Max, and Business plans, runs draw from your plan-included credits, then your add-on credits — both scoped to your individual user. On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms.
-* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted (insufficient credits error). With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App.
+* **Agent API keys** - Cloud agent runs authenticate as a named agent on your 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 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 runs can also clone repositories and open pull requests using the Oz by Warp GitHub App.
+* **Team API keys** - Legacy team-scoped keys that authenticate through the team's default service account. Use Agent API keys for new CI, GitHub Actions, scheduled, and other team automation workflows.
 
-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/).
+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/).
 
 ## Authenticating with API keys
 
@@ -75,7 +77,7 @@ The API Keys section in **Settings** > **Cloud platform** > **Oz Cloud API Keys*
 
 * **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, Agent, or Team
 * **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
@@ -94,7 +96,7 @@ Deleted keys are immediately invalidated and cannot be recovered. Any services o
 
 * **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 Agent API keys for automation** - For CI/CD and scheduled tasks, Agent API 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; Agent API 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.