Docs Reference

Keys

Which key does what: an agent’s key, a read-only account key, and when keys expire. For admins creating keys for agents and scripts. Give each agent its own key; use a read-only account key for reports.

Which key can use a Card

A key issued for an agent acts only as that agent: a proposal naming anyone else in actor_id is refused with actor_not_key_holder. Drawing on a Card needs such a key; a key bound to no agent is refused with key_not_bound_to_agent.

Create a key for this agent, on a Card’s page, issues the right key. To add a role to an existing key, use PATCH /v1/keys/{id} with {"add_roles": [...]}. Roles can’t be removed: revoke the key and issue another.

Read-only account key

For a script or report that reads the account: on API keys, choose Create API key, then Read-only account key. It is shown once and reads only GET /v1/me, /v1/me/activity, /v1/me/card-exceptions, /v1/me/mandates (with statements) and /v1/me/stream. Anything else answers 403 read_only_key.

Over the API: POST /v1/keys {"label": "…", "roles": ["viewer"]} with no agent_id.

Key expiry

Account keys always expire: in 90 days by default, at most a year. An agent’s key doesn’t expire unless you set expires_at. An expired key answers 401.