> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, the principal they act as, and when to use a service user.

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

```bash theme={null}
curl -H "Authorization: Bearer $CAPY_API_KEY" \
  "https://api.capy.ai/api/v1/threads?projectId=$PROJECT_ID"
```

## 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.