REST API

The API is a Cloudflare Worker. All application endpoints are under /v1 and require authentication. Values are always ciphertext — the API neither encrypts nor decrypts.

Authentication

Send one of:

• Authorization: Bearer <jwt> — a Stytch B2B session JWT (web sessions), or a machine (M2M) access token.
• Authorization: Basic base64(client_id:client_secret) — machine (M2M) client credentials. The API runs the OAuth 2.0 client-credentials exchange server-side and authorizes the caller as a machine client — the same credential used on the hosted metadata plane (mcp.seekrit.dev). It holds no key material and cannot decrypt; use it to bootstrap an admin service token, then switch to that token for anything that touches ciphertext.
• Authorization: Bearer skt_… — a service token. Its stored role is member (runtime credential) or admin (passes admin-gated routes, for headless provisioning). owner is never issued to a token. A service token is never a valid Basic credential — it carries a private key.
• Authorization: Bearer skc_… — a CLI session, created by seekrit login and authorized in the dashboard. It authenticates as the user who authorized it, with that member's role in every org they belong to. It carries no key material, so decryption still needs that user's passphrase-unlocked private key.

Errors use { "error": { "code": "...", "message": "..." } } with a matching HTTP status (400, 401, 403, 404, 409, 429, 500). Organizations you don't belong to return 404. One code is recoverable rather than final: mfa_required (403) means the caller must re-verify their second factor and retry (see CLI sign-in below).

Signup (agent self-service)

Also reachable as POST https://mcp.seekrit.dev/signup (the hosted MCP server proxies to this endpoint).

CLI sign-in (browser-approved)

What seekrit login drives. The CLI generates its own session token, registers only the SHA-256 hash, and a human authorizes that hash in the dashboard — so the credential never travels through the API, and an approval response carries nothing secret.

Manage the resulting sessions under Identity.

Health

Identity

Organizations

Applications & environments

An environment is owned by either an application or a group; applicationId and groupId are both present on the row, with the unused one null.

Environment lists exclude branches — they're returned by the branch endpoints below.

Each environment returned by GET /v1/orgs/:orgId/apps/:appId and GET /v1/orgs/:orgId/groups/:groupId also carries a canDecrypt boolean: whether the calling principal holds a key grant for that environment. Secret names and versions are visible to any member, but values only decrypt with a grant — so the dashboard uses canDecrypt to lock the environments you can't read. It's computed per request, not a stored field.

Branches

A branch is an ephemeral environment overlaying another: an ordinary environment row with a parentEnvironmentId and an expiresAt. It stores only the values that differ; the rest resolve from its parent at read time, so creating one copies and re-encrypts nothing.

ttlSeconds omitted takes the default (7 days); pass an explicit null for no expiry. The cap is 30 days. Expired branches are deleted automatically, along with their overrides, key grants, and any service token bound to them.

grants wraps the branch's new DEK to principals that already hold a grant on the parent (get their public keys from …/envs/:envId/grantees) — a grant naming anyone else is rejected. Creating a branch requires a grant on the parent, not an admin role: it conveys no access the caller doesn't already have. Parents must be application environments and must not themselves be branches.

Groups

A group is a reusable, org-scoped secret bag. Its environments (matched by slug) reuse the same secret and key-grant endpoints above.

Composition

Which groups an application environment pulls in, and their precedence.

Resolve

For a service token, the org + app + environment come from the token itself. For a user session pass ?env=<envId>. Repeat ?with=<groupSlug>:<envSlug> to resolve specific groups at a different slug. Add ?branch=<slug|id> to read an ephemeral branch of that environment — a service token stays bound to its own environment, so it can only name branches of that one. Returns { scope, layers }, where layers are ordered lowest-precedence first (composed groups → the app environment → the branch's overrides) and each carries its environmentId, secret ciphertexts, and the DEK wrapped to the caller. A branch resolve additionally reports scope.branchOf, and needs a grant on every layer including the parent — so branch access never exceeds parent access. The client decrypts and merges; the server sees only ciphertext. The language SDKs, CLI, and seekrit-run all implement this same decrypt-and-merge against this endpoint.

Secrets

Values are opaque ciphertext blobs produced by the client.

Key grants

KMS keys

Client-side managed keys for application-layer encryption and signing. Material is generated by the client and stored only as wrapped grants; sign keys also publish a public key per version. Management is (admin); using a key needs a grant. See Managed keys.

Recovery

Customer-controlled M-of-N recovery. The client generates and Shamir-splits the recovery key; these routes carry only the recovery public key, opaque wrapped shares, and ciphertext grants. Management is (admin); a custodian reads their own share and contributes to a ceremony. See Customer-controlled recovery.

Service tokens

A service token may read or write secrets only for environments it holds a key grant for — its bound environment and the group slices composed into it. It cannot address other environments in the org.

Honey tokens

Decoy credentials that grant nothing and alert on use. All routes are (admin), and gated on the Honey tokens plan feature. See the guide.

There is no endpoint that trips a honey token, because tripping isn't an operation: presenting one as Authorization: Bearer skt_… on any route records the trip, alerts the org's admins, and returns the same 401 unknown service token an unregistered token receives. The responses are identical by construction so a decoy can't be identified by probing.

Temporary access (leases)

Vault-style short-lived credentials. All routes are (admin).

Secret rotation

Managed, scheduled replacement of a stored secret's value. All routes are (admin). No route returns a secret value; a rotated value is read back through the normal secret/resolve paths. See Secret rotation.

Audit

Plans & billing

Read the org's plan, current metered usage, and start self-serve billing. See the plans & billing guide.

usage[] is the metered dimensions, each { key, metric, label, quantity, included, available } — quantity is the current usage for this period, included is what the plan covers before overage (null = unlimited), and available is false when a metric can't be measured (shown as unknown, not zero). manage reports which self-serve actions this deployment supports: { checkout, checkoutFamilies[], portal }.

Audit log export (OTLP)

Stream an organization's audit trail to your own SIEM/observability tooling. See the audit log export guide.

Agent access policy

Which upstream each agent may reach, with which credential, for which operations. The policy bundle is signed in the publishing admin's browser and is opaque to the API — see the agent access policy guide.

Third-party sync

Push an environment's resolved secrets to a platform that holds its own copy. See the third-party sync guide.