API overview

The Sigil HTTP API is split into three lanes by audience and auth model:

Lane	Base path	Auth	Audience
Wallet	/v1/wallets/...	publishable key + end-user JWT	the iframe (rarely you directly)
Server-to-server	/v1/s2s/...	secret key (sk_live_…)	your backend
Portal	/v1/orgs/..., /v1/me, …	Kratos session cookie	the developer portal (rarely you directly)

Production base URL: https://api.sigilkeys.com.

Response envelope

Every JSON response uses one shape:

{ "data": { ... }, "error": null }

On error:

{
  "data": null,
  "error": {
    "code": "wallet_not_found",
    "message": "no active wallet for this user"
  }
}

Stable error.code strings — safe to switch on. The message is human-readable and may change.

Status codes

• 200 / 201 / 204 — success
• 400 — your request was malformed
• 401 — auth missing or invalid
• 403 — auth was OK but not allowed for this resource
• 404 — resource not found
• 409 — conflict (e.g. wallet already exists)
• 410 — expired (recovery process timed out)
• 429 — rate limited
• 5xx — Sigil bug or upstream outage; safe to retry with backoff

Pagination

List endpoints accept limit (default 50, max 200) and offset. They return { items, total, limit, offset } so you can compute pagers yourself.

Idempotency

Wallet creation is idempotent on (organization_id, user_identity_id). Sending the same POST /v1/wallets twice for the same authenticated end user returns 409 wallet_exists with the existing wallet’s data.

Recovery shares are idempotent on (wallet_id, polynomial_version).