API endpoint reference

Every route, grouped the way you will look for them. Paths are relative to /api, and {…} segments are slugs.

Read the API overview first for authentication, errors and pagination — none of it is repeated here.

Version

Answered at both https://<host>/api/version and https://<host>/version — the same body, no redirect between them. The second is there because a version check is the one request made by someone holding a hostname and nothing else.

{
  "name": "xecret",
  "version": "0.1.0",
  "commit": "a1b2c3d",
  "builtAt": "2026-08-17T12:00:00Z"
}

The only unauthenticated GET that answers with data rather than a sign-in redirect, and the only endpoint that touches no database. Use it to check what a deployment is running before reporting a bug against it, and to watch a deploy roll out.

commit is git describe --always --dirty, so a build made from a modified tree says a1b2c3d-dirty. Both commit and builtAt read unknown on a build that did not come from scripts/deploy-web.sh — a local next build, or CI.

It reports the build, never the install: no environment name, no bindings, no dependency versions, no identity-provider or database detail. Those describe how one deployment is configured, which is not public.

Auth

Signing in is a sequence of browser navigations, not an API call: nothing on this server accepts an identity-provider token, and there is no endpoint to post a password to. A refused sign-in redirects to /sign-in?error=<code>, which shows a fixed sentence for that code. The specific reason is logged and never shown: telling a caller which part of a forged request to fix is a gift.

Re-authentication for a vault reset

Resetting a vault ends access to everything it held — the old vault is kept, recoverable, for seven days, then deleted for good — so it asks for proof twice, in order: a fresh sign-in (/auth/login?reauth=1, which makes the provider ask for a credential even if it remembers you), then a one-time code emailed to you. Browser sessions only, and usable while the vault is locked — which is the point. A refused re-authentication is a 403, never a 401, so it does not sign you out.

Recovering a reset vault

Inside its seven days, a reset vault can be brought back into the vault you have now, in the browser, with its old passphrase or one of its recovery codes (see Vault reset and archive). These endpoints need an unlocked session — re-sealing the old keys into the current vault needs it open — and answer only the vault's owner, only inside the window: the same 404 for anything else, a malformed id included.

CLI authorization

How xecret login obtains a token. An RFC 8252-style loopback flow with PKCE, against this server rather than the identity provider.

The code is consumed before the PKCE check, so a failed binding kills it rather than leaving it guessable.

Organisations

Projects and environments

Both deletes are soft. A hard delete would orphan the audit records saying the thing existed and who removed it.

Creating a project or an environment also creates the encryption keys, in the same transaction. A project arrives with development, staging and production, so POST /orgs/{orgSlug}/projects carries the keys for all three: { name, slug?, description?, environments: [{ slug, id, keys: { grant } }] }, where each slug names which of the three defaults the entry is for. Both creates need a browser session with an unlocked vault — the keys are generated there and sealed to you — and are refused for a CLI or service token. An environment without a key cannot hold a secret and cannot be repaired.

Secrets

The masked listing and the reveal endpoint are separate routes on purpose. Decryption happens in exactly one handler, so "where can a plaintext secret be produced?" has a one-line answer a reviewer can verify by searching the code.

Bulk read

The path xecret run depends on.

One environment, every current secret, decrypted server-side. Its budget is at most three database queries and zero outgoing network calls, constant in the number of secrets.

Audited once per call as secret.read with a count — not once per secret, which would make a 200-secret pull write 200 audit rows and turn the audit table into a denial-of-service surface against itself.

Import and export

The dry run and the real import call the same planning function, so the preview cannot disagree with the outcome — including a refusal for the plan's limit on secrets per environment.

Plan limits

Every plan's limits apply from the day they are published, and only to creating something. At a limit, the next one is refused with 403 plan_limit, whose plan block names the resource, the limit, your plan and the plan that would allow more:

Only live things count: deleting a project or environment, or revoking a token, frees its place, and an expired token holds none. Nothing you already have past a limit — after a downgrade, say — is deleted: it stays readable and editable, and only adding more is refused. The exception is webhooks on a plan that allows none, which are kept but paused — they send nothing, and cannot be edited, switched back on or tested until the plan allows them (switching one off or deleting it always works). Creating an organisation past the account's limit, and inviting past the organisation's seats, answer 409 conflict instead, with the same information in the message.

Environments and policies

The features in Environments and policies. Every write here is end-to-end encrypted: the client encrypts, the server checks shapes, names and permissions, and stores. A plan refusal is 403 plan_limit naming the plan that would allow it; none of these is ever asked of a read of the environment itself.

A server-mode environment whose plaintext export is disabled refuses …/export and document-format pulls with 403 export_disabled:, and marks the JSON pull xecret run reads with x-xecret-plaintext-export: disabled.

Members, invitations and grants

Custom roles

Enterprise only. A custom role narrows a built-in role — it can never give anybody more than the role it is based on. See Teams and access.

Single sign-on

SAML and OIDC single sign-on through WorkOS, set up by your IT admin in WorkOS's setup portal. From a browser session only (a CLI token is refused). Owners and admins can read the status and switch a policy off; only owners can turn SSO on, open the setup portal, or switch a policy on — whoever does those decides which identity provider vouches for every member. Turning anything on also needs the single sign-on add-on. Every route answers with the same sso status: whether SSO is on, ssoRequired, jitJoinEnabled, the seat limit, whether the add-on is held, and — once on — the connections and domains WorkOS reports (null, with providerReachable: false, if WorkOS cannot be reached) and membersOutsideVerifiedDomains, how many members your identity provider cannot sign in.

Tokens

A created token's value appears in exactly one response and is never retrievable again. No listing function selects the stored hash.

Audit

The response includes the window actually scanned, because the range is clamped to 90 days and a caller that asked for more must be told it got less.

Next

• Tokens — obtaining and scoping a credential.
• The API overview — errors, CSRF, rate limits.
• The audit log — what each event means.