ckrets.aickrets.ai Beta
Menu
Get a free keyFree key
Docs menu

For agents: /docs/endpoints.md is this page as Markdown.

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; the full schemas in /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, 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.

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.