API keys for the Oz CLI

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.

Personal vs. agent keys

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. Use a personal key when the run should act on your behalf — for example, developer-triggered API automation, or the Enterprise Analytics API, which only accepts personal keys.
• Agent API keys run as a cloud agent 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 or the Warp app. Both surfaces produce keys that authenticate the CLI and SDK identically.

From the Oz web app (recommended)

1. Open the Oz web app settings page.
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 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. 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.

API key management interface in Warp settings.

How key type affects billing and GitHub access

The key type determines who the run is attributed to, which credit pool is billed, and which GitHub credentials the agent can use.

Personal API keys

• Run as you.
• On Build, Max, and Business plans, use your plan-included credits, then your add-on credits. On Enterprise plans, use the team-scoped credit pool.
• Use your GitHub permissions. Code changes are attributed to your GitHub account.

Agent API keys

• Run as a cloud agent on your team.
• On Build, Max, and Business plans, bill the team owner: the owner’s plan-included credits, then the owner’s add-on credits. With auto-reload on, usage can trigger a reload on the owner’s pool, subject to the team-wide monthly spend cap. On Enterprise plans, use the team-scoped credit pool.
• Use the Oz by Warp GitHub App when team GitHub authorization 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 and 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. Environment variables are recommended for security and easier reuse across multiple commands.

Via environment variable (recommended):

$ export WARP_API_KEY="wk-xxx..."
$ oz agent run --prompt "analyze this codebase"

Via command flag:

$ oz agent run --api-key "wk-xxx..." --prompt "analyze this codebase"

Note

API keys start with the prefix wk-. If your key doesn’t have this prefix, it may be invalid or from an older format.

Managing API keys

The Oz web app settings page 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.
• 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.

Deleting API keys

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 and may return an authentication_required error.

Best practices

• 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 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.