API reference

HTTP reference for the WithPasskey broker. Base origins: https://api.withpasskey.xyz (API + RP-facing ceremonies), https://id.withpasskey.xyz (hosted enroll/recover pages).

Table of contents
  1. Relying-party surface
  2. Hosted pages (id.withpasskey.xyz)
  3. Ceremony internals (browser ↔ broker)
  4. Admin surface — Bearer ADMIN_TOKEN
  5. Identifier prefixes
  6. Errors

Relying-party surface

routemethodpurpose
/authorizeGETOIDC entry — client_id + verified redirect_uri + PKCE S256 → redirects into the hosted ceremony
/v1/tokenPOSTexchange one-time pkc_… code + client_secret + code_verifier → {id_token, assertion, expires_in: 120}
/.well-known/jwks.jsonGETpublic JWKS for assertion verification (kid-pinned)
/v1/enroll-ticketPOSTclient_id + client_secret → one-time pkt_… ticket + hosted enrollUrl
/v1/enrollPOSTticket → {requestId, registration options}
/v1/webauthn/registration/verifyPOSTattestation → stores public credential, links user, returns pkr- recovery codes on first enrollment
/v1/recoverPOSTpkr-… code → registration options for a new passkey on the same user

Hosted pages (id.withpasskey.xyz)

pathpurpose
/ceremony?request=…passkey sign-in ceremony UI (entered via /authorize)
/enroll?ticket=pkt_…hosted passkey registration (first enrollment shows recovery codes once)
/recoverrecovery-code → new passkey on the existing account

Ceremony internals (browser ↔ broker)

routemethodpurpose
/v1/webauthn/authentication/optionsPOST{requestId} → assertion options bound to the pending ceremony
/v1/webauthn/authentication/verifyPOST{requestId, response} → verifies assertion, mints code, returns redirect
/healthzGETliveness
/readyzGETreadiness (checks DB)

Admin surface — Bearer ADMIN_TOKEN

Break-glass control plane at https://api.withpasskey.xyz/admin/*. The customer console calls it server-side only — the token never reaches a browser. Mint it as a 32-byte random secret; treat it as root.

routepurpose
POST /admin/tenants · GET /admin/tenantscreate + list tenants
POST /admin/apps · GET /admin/apps · GET /admin/apps/:idapplications (returns pk_ client_id; body env: test|live)
POST /admin/apps/:id/domainsadd an origin — dev|dns-txt|well-known verification
POST /admin/apps/:id/keys · POST /admin/credentials/:id/revokemint sk_/pk_ secrets, revoke credentials
GET /admin/jwks · POST /admin/jwks/rotatekeyring per env — required before the first token exchange
POST /admin/ticketsoperator-minted enrollment tickets
POST /admin/users/:userId/recoveryoperator-minted recovery codes (shown once)
GET /admin/audit · GET /admin/overviewaudit events + counters
POST /admin/console-seed · POST /admin/demo-seedbootstrap the console app / a demo relying party

Identifier prefixes

prefixthing
pk_test_/pk_live_client_id (public identifier)
sk_test_/sk_live_client_secret (server-only)
pkt_enrollment ticket (one-time)
pkc_authorization code (one-time, 60s)
pkr-recovery code (one-time, shown once)
k_JWKS key id

Errors

Uniform envelope {error:{code,message}}. Codes you will meet: invalid_client (401, unknown client or bad secret), invalid_grant (400, code/PKCE/redirect mismatch), invalid_ticket/invalid_code (400), unknown_credential/assertion_failed/attestation_failed (400), expired (410), rate_limited (429), internal (500).