API keys & grants

Create, rotate, and revoke API keys, and scope each key to specific providers, actions, or tool-sets with grants.

An API key authenticates SDK and HTTP access and resolves to a single environment. Keys are shown in plaintext once at creation/rotation, then stored only as a PBKDF2-SHA256 hash and displayed masked (first8…last4).

Manage keys

Routes are under /api/v1/api-keys (JWT auth).

Method	Path	Purpose
`GET`	`/api-keys/{env_id}`	List keys for an environment (masked)
`POST`	`/api-keys/{env_id}`	Create a key — returns the plaintext `secret` once
`POST`	`/api-keys/{secret_id}/rotate`	Rotate — returns a new plaintext `secret` once
`PUT`	`/api-keys/{secret_id}/grants`	Replace the key's grant set
`DELETE`	`/api-keys/{secret_id}`	Delete (the default key can't be deleted)

Create a key

curl -X POST https://your-host/api/v1/api-keys/1 \
  -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" \
  -d '{ "display_name": "ci-agent", "grants": { "provider_config_key": "github", "action_name": "list-repos" } }'
# → { "id": …, "secret": "sk_…", "grants": {…} }   ← secret shown ONCE

Grants (agent-scoped keys)

A key with no grants can use every tool in its environment. Grants narrow it to specific providers, actions, or a tool-set:

provider_config_key — limit to one provider (use * for all).
action_name — limit to one action (provider/* matches every action for a provider).
tool_set_id — bind the key to a named tool-set.

Grants are enforced on every action and proxy call. A call outside the grant returns an opaque 403 Insufficient permissions — the message never leaks which provider/action was blocked. Grants compose with policies: grants decide what a key may reach; policy decides what happens when it runs. The same grant allowlist also scopes MCP OAuth tokens.

Store keys in a secret manager, never in source or prompts. Rotate on a schedule and on suspected exposure — rotation invalidates the old key immediately.

Manage keys

Create a key

Grants (agent-scoped keys)

On this page