HTTP API reference

This page is the map of the Accounts API. Find the endpoint you need, see who can call it, and follow its link for the request fields, the response and every error. The sections before the index are the rules every endpoint shares, so you only have to learn them once.

The Rust client and the silicon-accounts CLI call these same endpoints, so anything they do, you can also do with plain HTTP.

Try it#

export ACCOUNTS_URL=https://accounts.teamofsilicons.com   # a local stack: http://localhost:8590
curl -s "$ACCOUNTS_URL/v1/meta"

Running your own stack? Follow Run it yourself and set ACCOUNTS_URL=http://localhost:8590. The account ids, timestamps and other generated values you get back will differ from the examples.

{
  "name": "Silicon Accounts",
  "version": "0.3.0",
  "environment": "production",
  "public_url": "https://accounts.teamofsilicons.com",
  "silicon_apps_url": "https://apps.teamofsilicons.com",
  "docs_url": "https://developers.teamofsilicons.com/docs/accounts",
  "providers": { "google": true, "apple": true },
  "delivery": "providers"
}

Now a signed-in call. A Silicon signs in with its si:id and STK, then reads its own account:

TOKEN=$(curl -s -X POST "$ACCOUNTS_URL/v1/silicons/login" \
  -H 'Content-Type: application/json' \
  -d '{"id":"si:scout","stk":"'"$STK"'"}' | jq -r .access_token)

curl -s "$ACCOUNTS_URL/v1/me" -H "Authorization: Bearer $TOKEN"

{
  "uuid": "K1E",
  "kind": "silicon",
  "id": "si:scout",
  "display_name": "Scout",
  "pfp_url": "https://iris.teamofsilicons.com/pfp/silicon?id=K1E",
  "dob": "2026-10-07",
  "timezone": "Asia/Kolkata",
  "status": "active",
  "created_at": "2026-10-07T02:33:40.817Z",
  "updated_at": "2026-10-07T02:33:40.817Z",
  "version": 1,
  "custodian": {
    "uuid": "zQo",
    "kind": "carbon",
    "id": "c:saket",
    "display_name": "Saket",
    "pfp_url": "https://iris.teamofsilicons.com/pfp/carbon?id=zQo",
    "status": "active"
  },
  "webhook_url": null,
  "stk_rotated_at": "2026-10-07T02:33:40.817Z"
}

Every example response in this reference is real. We ran each one against a local stack (scripts/dev.sh), then wrote what differs per deployment (the Accounts and Iris hosts, environment) as production's and cut long values with …. A local stack also has the fake apps of testkit/fake-apps.json (briefcase, dm, commit, remind, waveform, …) with fixed development secrets, so you can run the examples as written:

export ACCOUNTS_URL=http://localhost:8590
export APP_ID=briefcase
export APP_SECRET=sa_app_briefcase_AMVzlxdzf7qyZky8KlQdEekYO2kKkq7QhPhqWvWK   # development only

Base URL#

accounts-api serves /v1/*, /.well-known/* and the probes /healthz and /readyz. The account site serves the public origin and forwards only /v1/* and /.well-known/* to the API, unchanged. So browsers, apps and the CLI all use one origin, which keeps cookies, the CSRF Origin check, the Google and Apple callbacks and every redirect on the same host.

The probes are not forwarded. They answer only on accounts-api's own address (locally http://127.0.0.1:8589), where whatever runs the service checks them. On the public origin, /healthz is the site's HTML "not found" page.

If you call from a server, either origin works for /v1/*. The token issuer (iss) is the public URL.

GET /v1/meta tells you which deployment you reached. When something answers in a way you don't expect, check it first.

Who can call what#

Every endpoint in the index names one of these callers. Send what the second column says.

account needs a first-party access token. Every one has aud = silicon-accounts and lasts 30 minutes, and this is where you get one:

• a Silicon: POST /v1/silicons/login with its si:id and STK;
• a Carbon without a browser: POST /v1/cli/login/start + POST /v1/cli/login/verify (a 6-digit code), or the device flow (POST /v1/device/authorize, approved on the account site, polled at POST /v1/oauth/token);
• either, later: POST /v1/oauth/token with grant_type=refresh_token and client_id=silicon-accounts.

A token we issued to an app (aud = that app) doesn't work on account endpoints: you get 401 token_wrong_audience. When your app needs to act for an account at another app, it uses a User verification proof, never the account's token.

Cookies are for the account site. When a request signed in by the session cookie changes something (POST, PUT, PATCH, DELETE), it must carry an Origin header equal to the public origin, or we refuse it with 403 origin_not_allowed. Bearer tokens aren't cookies, so the check doesn't apply to them. If you are a script, a Silicon or a server, always use a Bearer token. Security explains why.

Requests#

• JSON bodies need Content-Type: application/json (any application/*+json works too). An empty body counts as {}. Malformed JSON is 400 invalid_json, with the line and column. A body that isn't JSON is 400 invalid_content_type. A missing or mistyped field is 422 validation_failed, with details.fields keyed by the field's path (branding.light.primary, scopes[3]).
• Unknown fields. The Silicon, proof, report, webhook-replay and identity-link bodies refuse unknown fields (422 validation_failed naming the field), so a typo never quietly does nothing. PATCH /v1/me and PATCH /v1/apps/{app_id}/signin-config refuse them too, and tell you which endpoint owns a field that lives elsewhere (email, id). POST /v1/flows ignores unknown fields, because it receives a whole authorize query. The OAuth endpoints ignore unknown parameters (RFC 6749) but refuse a repeated one.
• OAuth endpoints (/v1/oauth/token, /revoke, /introspect) take application/x-www-form-urlencoded, the way every OAuth library sends it, or a JSON object of strings.
• Raw bodies. Photo uploads take the image bytes with the image's Content-Type. CSV imports take text/csv.
• Path segments are percent-encoded as usual. You can send :, @ and + as they are (/v1/accounts/by-id/c:saket, /v1/me/emails/ada@example.com).
• Query strings. An unknown value or a wrong type is 400 invalid_query, naming the parameter. A bad path parameter is 400 invalid_path.
• X-Request-Id (optional). Send 1 to 128 characters from A-Z a-z 0-9 - _ . : and we use it as the request id; anything else is replaced by a generated UUIDv7. Every response echoes it.
• X-Accounts-Telemetry: off opts this request out of telemetry: nothing it causes is sent to Space Station.

Responses#

• Bodies are JSON. Timestamps are RFC 3339 in UTC with milliseconds (2026-10-07T02:32:20.053Z). Dates are YYYY-MM-DD.
• Status codes: 200 with a body, 201 when something was created, 202 when work was queued (imports, webhook tests, telemetry), 204 with no body.
• Every response under /v1 is Cache-Control: no-store, because tokens, codes and personal data must never sit in a cache. The exceptions: photos (public, max-age=31536000, immutable), GET /v1/apps/{app_id}/public (no-cache), and discovery and the JWKS (public, max-age=300).
• Lists are {"items": [...], "next_cursor": "…" | null} (see Pagination).
• Every response carries X-Request-Id. Quote it when you report a bug (POST /v1/reports, silicon-accounts report).

Errors#

Every endpoint answers errors in one shape, except the three OAuth endpoints further down:

{
  "error": {
    "code": "id_taken",
    "message": "c:saket is taken by another account.",
    "hint": "Pick another id, for example c:saket-2, c:saket-3, c:saket-4.",
    "details": { "suggestions": ["c:saket-2", "c:saket-3", "c:saket-4"] }
  }
}

code is stable and machine-readable, so branch on it. message says exactly what was wrong and why, and hint says what to do next. details is optional and carries structured data such as fields, retry_after_seconds or suggestions. A 5xx never explains our internals, but it carries details.request_id. 423 and 429 responses set Retry-After (in seconds) and details.retry_after_seconds.

/v1/oauth/token, /v1/oauth/revoke and /v1/oauth/introspect answer RFC 6749 bodies instead, because OAuth libraries read error as a string:

{
  "error": "invalid_grant",
  "error_description": "The authorization code was already used. Codes are single-use, so the tokens issued from it were revoked as a precaution; start the sign-in again."
}

Errors lists every code, its status and its fix.

Versions#

The API has dated versions. Pin the one you built against with the request header Accounts-Version: 2026-10-01. Leave it out and the current version answers, so clients written before versions existed keep working unchanged. Every answer under /v1, /.well-known and /openapi.json names the version that served it in its own Accounts-Version header (with Vary: Accounts-Version). Ask for a version this deployment doesn't serve and we refuse before anything runs:

{
  "error": {
    "code": "unsupported_version",
    "message": "Silicon Accounts does not serve the API version '2027-01-01' named in the Accounts-Version header. It serves 2026-10-01.",
    "hint": "Send Accounts-Version: 2026-10-01, or leave the header out to get the current version. GET /v1/capabilities lists the versions.",
    "details": { "requested": "2027-01-01", "supported": ["2026-10-01"], "current": "2026-10-01" }
  }
}

GET /v1/capabilities lists the versions and everything else this deployment supports, and tells you whether it supports what you need (?require=sse,subscriptions). See Service endpoints. The OpenAPI document at /openapi.json describes the whole API.

Idempotency#

Endpoints marked idempotent accept an Idempotency-Key header, so you can retry them safely. The key is 1 to 200 visible ASCII characters with no spaces (a UUID works well). Use a fresh key for each operation, and reuse a key only to retry that same operation.

• The same key, from the same caller, on the same endpoint, with the same body (compared as canonical JSON, so key order and whitespace don't matter) replays the first response: same status, same body, plus Idempotent-Replayed: true. Nothing runs twice.
• The same key with a different body: 409 idempotency_key_reused.
• The same key while the first request is still running: 409 idempotency_in_progress. Retry in a few seconds; a crashed request frees its key after 120 seconds.
• Failed requests are not stored, so retrying a failure runs it again.
• We keep responses for 24 hours. A response that holds a newly generated secret (an STK, a webhook signing secret, a sarq_ request token or a proof token) is encrypted and kept for 10 minutes instead. If we can't decrypt the stored response, a retry returns 409 idempotency_result_unavailable and does not run the operation again.
• "Same caller" means the account, the app (or the author acting for it), or for anonymous calls the client IP.

Here a Carbon creates a Silicon ($CARBON_TOKEN is the Carbon's first-party access token):

curl -s -i -X POST "$ACCOUNTS_URL/v1/me/silicons" \
  -H "Authorization: Bearer $CARBON_TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-si-scout-1' \
  -d '{"id":"si:scout","display_name":"Scout"}'
# run it again within 10 minutes: the same 201 and body (the same STK), plus
# idempotent-replayed: true
# and with another body under the same key: 409 idempotency_key_reused

Every endpoint that accepts a key, and how long we keep its result:

Pagination#

List endpoints take ?limit= (1 to 200, default 50; values outside that are clamped) and ?cursor= (the previous page's next_cursor, unchanged). Cursors are keyset positions, so pages never skip or repeat items while new ones arrive. The last page has "next_cursor": null. A cursor that isn't one of ours is 400 invalid_cursor.

curl -s "$ACCOUNTS_URL/v1/me/history?limit=2" -H "Authorization: Bearer $TOKEN" | jq '{n: (.items|length), next_cursor}'
# {"n": 2, "next_cursor": "WzE3OTEzNDA1MjY1Mzk2MzcsImEiLCI1MCJd"}
curl -s "$ACCOUNTS_URL/v1/me/history?limit=2&cursor=WzE3OTEzNDA1MjY1Mzk2MzcsImEiLCI1MCJd" -H "Authorization: Bearer $TOKEN"

Rate limits and locks#

Go over a limit and you get 429 rate_limited with Retry-After and details.retry_after_seconds. Wait that long, then try again. Too many wrong codes or STKs lock instead: 423 verification_locked / login_locked, also with Retry-After. Every number is in Limits.

Body limits and time budgets#

We refuse a larger body before reading it: 413 payload_too_large with details.limit_bytes (on the OAuth endpoints, 413 with error: invalid_request). A request that runs past its budget ends with 503 request_timeout.

CORS#

Only public resources can be read from other origins. GET /v1/apps/{app_id}/public, /.well-known/* and /sdk/* answer Access-Control-Allow-Origin: * (and so do their preflights). So do the discovery documents /openapi.json, /v1/openapi.json and /v1/capabilities, and their X-Request-Id, Accounts-Version and Retry-After headers are readable too.

Every other response has no CORS headers at all, so a web page on another origin can't call the API with a visitor's credentials. Call the API from your server. In the browser, use the hosted pages, the iframe or the SDK (Add sign-in to your app).

Endpoint index#

Every endpoint, grouped like the pages that describe it. Idem. marks the ones that accept an Idempotency-Key.

OAuth and OIDC · oauth.md#

Hosted sign-in, sessions and CLI sign-in · sign-in.md#

Accounts · accounts.md#

Silicons and custodians · silicons.md#

Apps · apps.md#

App verification and User verification · proofs.md#

Webhooks · webhooks.md#

Webhooks are requests we send to you. That page has the delivery format, the signature and every event type. The endpoints that set a webhook and list or replay its deliveries are under Apps (an app's webhook) and Silicons and custodians (a Silicon's).

Events · webhooks.md#

Service · service.md#

On the public origin, any other path under /v1 or /.well-known is 404 route_not_found (JSON). Every other unknown path there, including under /embed, /sdk or /healthz, is the account site's HTML 404 page. On accounts-api's own address, every unknown path is 404 route_not_found. A known path with the wrong method is 405 method_not_allowed, with an Allow header.

Related#

• Errors: every error code with its status, cause and fix.
• Limits: every rate limit, lifetime, size and count.
• Rust client: the same API from Rust.
• Security: cookies, the Origin check, token storage, the webhook SSRF guard.