Skip to main content
Every request to the public API authenticates with an API key sent as a bearer token:

​
Keys

A key is an opaque credential (capy_ followed by 43 random characters) scoped to one organization. Keys are minted only in the app under Settings → API; there is no API endpoint for minting, renaming, or revoking keys, so possession of a key never lets you make more keys.
  • The plaintext is shown exactly once at mint. Capy stores only a digest, so a lost key is a revoke plus a new mint, never a recovery.
  • Keys optionally expire, set at mint only.
  • There is no rotate verb: rotation is minting a new key and revoking the old one, with the overlap under your control.
  • A missing, revoked, or expired key all answer the same capy/Unauthorized; the failure reason is deliberately not disclosed to the caller.

​
Every key acts as a principal

A key names one explicit acting principal: a human user or a service user. The key itself grants no authority: it’s possession proof plus organization selection, and every request re-resolves the live principal. That “acting as” has two consequences:
  • Attribution. Threads created with the key belong to the principal, usage bills attribute to it, and commits carry its identity: a human principal’s runs commit as that person, a service principal’s runs commit under the service user’s name with Capy’s bot address.
  • Permissions. The principal’s live state decides what the key can do, on every request. Remove a member from the organization and their keys stop authenticating on the next request; disable a service user and its keys stop the same way. Re-enabling a service user restores its keys without re-minting.
There are no per-key scopes today. A human key acts with your live membership role; a service key acts with the service user’s role and project access.

​
Service users

A service user is a non-human principal owned by your organization: no login, no email, just a name, a role, and project access. It’s the right principal for anything that outlives a person’s involvement:
  • Automations: an automation running as a departed teammate is auto-disabled when they’re offboarded; one running as a service user keeps working.
  • CI and integrations: a bot that creates threads from your pipeline shouldn’t act as whoever happened to set it up, in attribution or in permissions.
Service users carry:
  • a role: read_only (read and list only), read_write (create and drive threads within its project access), or admin (organization-admin operations on surfaces that accept a service principal; it can never own or delete the organization);
  • project access: all organization projects, or an explicit allowlist;
  • an optional monthly spend cap, checked before new billable work starts.
Create service users and mint their keys in Settings → API. Any member can create a read_only or read_write service user; creating an admin one takes an organization admin or owner.

​
Subscription grants for seat-billed models

Some models route through a subscription seat (Claude, Codex OAuth routes) rather than Capy’s metered billing. A service user can use those only through an explicit grant: a member lends their subscription to a specific service user, and the grant is checked live on every use: revoking it, or the member leaving the organization, cuts the route immediately. The grant is credential custody only, never billing delegation: Capy-billed work by a service user always bills your organization under the service user’s own identity. And there is no fallback: if the granted subscription is exhausted or revoked, the run fails on that model rather than silently switching to a different payer.

​
Practical guidance

Use your own key for exploration and personal scripts, where acting as yourself is the point. The moment something runs unattended (cron, CI, an automation’s run-as principal, a shared integration), give it a service user with the narrowest role and project access that works, and set a spend cap. You’ll revoke and re-mint human keys as people come and go; the service user’s key survives all of it.