API key scopes

Every API key carries a list of scopes, and every endpoint declares the scope it requires. A request succeeds when the key holds that scope. There is no implicit access: a key with no scopes can call Whoami and nothing else. Set scopes when you create a key, in the dashboard or through the API Keys endpoints. Dashboard sessions use the same scope vocabulary, resolved from your role’s permissions, so a rule you read here applies to humans and keys alike.

How scopes work

A scope is a resource:verb string, like agents:read or secrets:manage.

manage implies read. A key with agents:manage calls every agent endpoint, read or write. Stored scope sets are normalized: agents:read is dropped when agents:manage is present, and duplicates collapse.
* is full access. It is the only way to hold everything, including scope families added in the future. A set that contains * normalizes to * alone.
Two families are manage-only. Reads of secrets and account are as sensitive as writes, so no :read verb exists for them.

Scope reference

Scope	Grants access to
`agents:read`	Read agents, variations, schedules, and models
`agents:manage`	Create, update, publish, archive, and delete agents, variations, and schedules; enable, disable, and swap models
`objectives:read`	Read objectives, events and event streams, tasks, context windows, diagnostics, feedback, and uploads
`objectives:manage`	Create and continue objectives, approve or deny tool calls, submit feedback, compact, and create uploads
`tools:read`	Read tool sets and tools, fetch consumed OpenAPI specs, and search
`tools:manage`	Create, update, sync, omit, restore, archive, and delete tool sets and tools
`memory:read`	Read memory layers and entries
`memory:manage`	Create, update, and delete memory layers and entries
`api_keys:read`	Read a workspace’s API keys and the global key
`api_keys:manage`	Create, update, rotate, disable, enable, and delete API keys
`workspaces:read`	List workspaces, members, and profiles; read workspace details
`workspaces:manage`	Create, update, and archive workspaces; add and remove members
`secrets:manage`	Workspace secrets, tool set secrets, and AI provider keys, reads included
`account:manage`	Read the account; rotate the webhook signing key and challenge token
`*`	Everything, now and in the future

One endpoint is scope-free: Whoami answers for any valid credential, so a key can always identify itself.

Deny by default

A key’s scope set is the whole story. There is no grandfathering and no fallback.

A key with an empty scope set is a dead key: it authenticates, it can call Whoami, and every other endpoint denies it.
A missing scope denies the request even for reads. agents:manage does not help you list tool sets.
Full access is always an explicit grant: * on the key, or every scope spelled out (see the next section).

Managing keys with keys

API keys can mint other API keys, so the API enforces one rule to stop privilege escalation: a key can never produce access it does not hold.

Downscope only. Creating or updating a key with scopes the caller does not hold fails with PermissionDenied. Updates check this rule only when the scope set changes, so a narrow key can still rename a broader one.
Rotation requires dominance. Rotating a key returns that key’s fresh token, which is equivalent to minting it. The caller’s scopes must cover the target’s.
Granting * requires full access. Holding *, or holding the manage verb of every scope family, qualifies. Anything less does not, even if it covers most of the vocabulary.
Granting nothing is always allowed. Any caller can mint a dead key.

Disabled keys

An API key is either enabled or disabled. Disable a key with POST /v1/workspaces/{workspaceId}/api_keys/{id}:disable and its token stops authenticating on every endpoint, Whoami included, until you enable it again. The key, its scopes, and its token survive the round trip, which makes disable the right kill switch when you suspect a leak but are not ready to rotate.

Reading a denial

Scope denials return PermissionDenied with a google.rpc.ErrorInfo detail you can branch on. The domain is always api.cadenya.com.

Reason	Meaning	Metadata
`SCOPE_MISSING`	The caller does not hold the endpoint’s required scope	`required_scope`, `granted_scopes`
`SCOPE_NOT_HELD`	A key operation would grant, update, or rotate beyond the caller’s own scopes	`granted_scopes`
`API_KEY_DISABLED`	The presented token belongs to a disabled key	`api_key_id`

granted_scopes echoes the caller’s own scopes back as a comma-separated list. It reveals nothing the caller does not already hold, and it turns “why is this 403ing” into a one-glance diff:

{
  "code": 7,
  "message": "caller does not hold the \"agents:read\" scope required by this endpoint",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "SCOPE_MISSING",
      "domain": "api.cadenya.com",
      "metadata": {
        "required_scope": "agents:read",
        "granted_scopes": "memory:read,tools:read"
      }
    }
  ]
}

Scopes gate endpoints, not embedded fields

A scope controls which endpoints a key can call. It does not filter the responses of endpoints the key can call. When a response embeds a summary of a related resource (an agent’s info.createdBy profile, a tool set’s tool counts), that summary hydrates whether or not the key holds the related family’s scope. If a key can read the resource, it can read the whole resource.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

How scopes work

Scope reference

Deny by default

Managing keys with keys

Disabled keys

Reading a denial

Scopes gate endpoints, not embedded fields

​How scopes work

​Scope reference

​Deny by default

​Managing keys with keys

​Disabled keys

​Reading a denial

​Scopes gate endpoints, not embedded fields

How scopes work

Scope reference

Deny by default

Managing keys with keys

Disabled keys

Reading a denial

Scopes gate endpoints, not embedded fields