# Endpoints and credentials

What the ckrets.ai API answers today, what is planned, and what each kind of `Authorization: Bearer` can do. The
walk-throughs are in [For agents](/for-agents.md); the full schemas in [/openapi.json](/openapi.json).

Every path in `/openapi.json` carries `x-ckrets-stage`: `beta` (live in 0.9), `preview` (live but opt-in; none yet) or
`planned` (specified, not built: `501 not-in-v1`). Today a request signed without a key is anonymous (the signed-agent
tier is planned). `Authorization: Bearer` takes four kinds,
told apart by the prefix:

- a key, `ck_live_…`: everything its scopes allow (create, reveal what is addressed to it, status, revoke, `/v1/me/…`);
- a manage token, `ckm_…`: the status and revoke of the one secret it came with, nothing else;
- a CI job's OIDC token (a JWT whose `aud` includes `https://ckrets.ai`): create at free-key limits, and reveal what is
  addressed to that job;
- an account session, `cka_v1.…`: issued by the ckrets.ai passkey sign-in to a first-party app (Puzzlebox in v1), good
  for 12 hours with no refresh. It creates puzzle boxes at the account tier, lists and reads its own boxes
  (`GET /v1/me/secrets`, `GET /v1/me/secrets/{id}`), adopts an anonymous box (`POST /v1/me/secrets/adopt`), and reads the
  status of, revokes or tightens a box its account owns. It is not a key: it cannot mint or inspect a key, and on any
  other route it counts as no credential (the anonymous tier), so it reveals nothing addressed to a key. An agent never
  needs one.

Any other bearer is `401 invalid-credentials` on every route: send no `Authorization` rather than a bad one.

The launch set (v1):

- `POST /v1/secrets`: store a value under a policy (template, ttl, reveals, passphrase, audience, purpose; a puzzle policy and public metadata for the puzzle template); returns token, url, manageToken, a keyed digest with its digestKey, receipt. The digest is safe to log; keep the digestKey out of logs, since with both anyone can test guesses of the value.
- `GET /v1/secrets/{token}`: reveal once (every GET of a bearer token is the reveal: never use it to test or prefetch a token; `/public` is the safe check); `POST` the same path with a proof (a passphrase, never in a GET: a query string is never read; a commitment; or a ticket with a commitment or a verifier's verdict); the recipient proves its audience; returns a signed receipt.
- `GET /v1/secrets/{token}/public`, `POST /v1/secrets/{token}/attempts`, `PATCH /v1/secrets/{token}/policy`, `GET /v1/me/secrets`: public metadata, counted attempt tickets, owner policy changes that never widen the gate, the caller's own secrets.
- `GET /v1/secrets/{token}/status`: the creator's view; never the value.
- `DELETE /v1/secrets/{token}`: revoke with the creator's key or the manage token, both as `Authorization: Bearer` (the kind is read from the prefix: `ck_live_` key, `ckm_` manage token; a box an account owns, also `cka_v1.` account session).
- `POST /v1/keys`, `GET /v1/me/key`, `PATCH /v1/me/key`, `DELETE /v1/me/key`: mint a free key (body optional: label, email, domain, scope, clientEncryptionRequired), inspect it (its lease, scopes and whether it requires client encryption), require client encryption from then on (`{"clientEncryptionRequired": true}`; it cannot be turned off), revoke it (its unrevealed secrets then answer `410`; revealed ones and receipts stand, and their manage tokens still read status and revoke).
- `GET /v1/limits`: tier, limits, remaining creates, reset times, stamp parameters, lease window, and `stage` (`prod` is production).
- `POST /v1/requests`, `GET` and `DELETE /v1/requests/{requestId}`, `GET /v1/requests/{requestId}/public`, `POST /v1/requests/{requestId}/answer`: ask a person for a value through the page `/q/{requestId}` ([For agents](/for-agents.md#7-ask-a-person-for-a-password-or-a-code), section 7).
- `POST /v1/report`: report a token or URL with a `reason` (required); a bearer token is frozen pending review, an audience-bound one is recorded only. Whoever holds a bearer URL can reveal it, spend its passphrase attempts or freeze it with a report; to stop all three, name an audience.
- `POST /v1/receipts/verify`: convenience; verify offline when you can.
- `POST /v1/sessions` (first-party apps only: a Turnstile-backed session ticket for anonymous puzzle creates) and
  `POST /v1/me/secrets/adopt` (take an anonymous box into an account); the puzzle routes are on [the puzzle template page](/docs/puzzle.md).

Planned (specified, built after the beta is measured):

- `POST /v1/batches`, `GET /v1/batches/{id}`, `DELETE /v1/batches/{id}`: many secrets to many named recipients with a manifest receipt.
- `POST /v1/me/domain`, `POST /v1/me/domain/verify`: verify a domain for request pages and webhooks.
- `POST /v1/me/webhooks`, `DELETE /v1/me/webhooks/{id}`: signed events to the verified domain.
- `POST /v1/me/key/delegate` (planned): a narrower child lease for another agent, one level.