App keys

App keys (ocps_…) are for agents, scripts and servers that should only touch one app. Only a workspace key can make, change or revoke them. See Keys and spending limits for how limits work.

The key objectCopy Anchor Link

{
  "id": "key_…",
  "object": "scoped_key",
  "name": "Report agent",
  "app_id": "app_…",
  "service_id": "svc_…",
  "access": "read",
  "start": "ocps_3fQ1x",
  "created_at": "…",
  "last_used_at": null,
  "spend_limit": "5.000000",
  "spent": "0.000000"
}

Make a keyCopy Anchor Link

POST /api/v1/apps/{id}/keys

Returns 201 with the key object plus key: the secret itself, shown only this once.

Keys made by keysCopy Anchor Link

An app key can make keys too, for the sub-agents it hands work to, but never broader than itself:

• only for its own app (a workspace key can make keys for any app);
• read-only if it's read-only itself;
• within its spending limit, if it has one (see below).

Anything else is 403 key_out_of_scope, with the reason. A key that made other keys can change their limits or revoke them, and revoke itself, but no other keys.

Keys with a spending limit only make things saferCopy Anchor Link

Any key with a spending limit of its own, workspace key or app key, can only tighten things. Otherwise an agent could give itself room you never gave it. Such a key:

• can add a spending limit or lower one (on an app, an end user, the end-user default or another key), but not raise or remove one;
• can make read-only keys freely, but a key that can change things only with a spending limit of its own, no higher than what it has left;
• can pause an app, but not resume it;
• can list, test, rename and turn off webhooks, but not add one or change where one sends or what it sends.

A key's limit covers everything spent by the keys it made, and by the keys they made, revoked ones included. So handing a sub-agent a key never gets round a limit: when the family reaches it, every key in it is stopped. A key below with its own, smaller limit stops at that one first.

Anything else gets 403 limited_key, saying what the key may still do. You can always do these yourself in the dashboard, or with a key that has no limit. Over MCP, the tools that give an agent more room (create_app_key, set_app_spend_limit, set_end_user_spend_limit, pause_app, resume_app, create_webhook) are marked to ask you first.

List, limit or revokeCopy Anchor Link

What a key can reachCopy Anchor Link

Workspace-wide calls (/workspace, /balance, /usage, /prices, and listing or creating apps) need a workspace key. An app key sees its own app's usage at GET /api/v1/apps/{id}/usage.