# API reference · WithPasskey

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

Canonical: https://withpasskey.xyz/api-reference

Locale: en

*Published 2026-11-17 · updated 2026-11-17*

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

- [Relying-party surface](#b-h-rp)
- [Hosted pages (id.withpasskey.xyz)](#b-h-hosted)
- [Ceremony internals (browser ↔ broker)](#b-h-ceremony)
- [Admin surface — Bearer ADMIN\_TOKEN](#b-h-admin)
- [Identifier prefixes](#b-h-ids)
- [Errors](#b-h-err)

<a id="b-h-rp"></a>

## Relying-party surface

| route | method | purpose |
| --- | --- | --- |
| /authorize | GET | OIDC entry — client\_id + verified redirect\_uri + PKCE S256 → redirects into the hosted ceremony |
| /v1/token | POST | exchange one-time pkc\_… code + client\_secret + code\_verifier → {id\_token, assertion, expires\_in: 120} |
| /.well-known/jwks.json | GET | public JWKS for assertion verification (kid-pinned) |
| /v1/enroll-ticket | POST | client\_id + client\_secret → one-time pkt\_… ticket + hosted enrollUrl |
| /v1/enroll | POST | ticket → {requestId, registration options} |
| /v1/webauthn/registration/verify | POST | attestation → stores public credential, links user, returns pkr- recovery codes on first enrollment |
| /v1/recover | POST | pkr-… code → registration options for a new passkey on the same user |

<a id="b-h-hosted"></a>

## Hosted pages (id.withpasskey.xyz)

| path | purpose |
| --- | --- |
| /ceremony?request=… | passkey sign-in ceremony UI (entered via /authorize) |
| /enroll?ticket=pkt\_… | hosted passkey registration (first enrollment shows recovery codes once) |
| /recover | recovery-code → new passkey on the existing account |

<a id="b-h-ceremony"></a>

## Ceremony internals (browser ↔ broker)

| route | method | purpose |
| --- | --- | --- |
| /v1/webauthn/authentication/options | POST | {requestId} → assertion options bound to the pending ceremony |
| /v1/webauthn/authentication/verify | POST | {requestId, response} → verifies assertion, mints code, returns redirect |
| /healthz | GET | liveness |
| /readyz | GET | readiness (checks DB) |

<a id="b-h-admin"></a>

## 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.

| route | purpose |
| --- | --- |
| POST /admin/tenants · GET /admin/tenants | create + list tenants |
| POST /admin/apps · GET /admin/apps · GET /admin/apps/:id | applications (returns pk\_ client\_id; body env: test|live) |
| POST /admin/apps/:id/domains | add an origin — dev|dns-txt|well-known verification |
| POST /admin/apps/:id/keys · POST /admin/credentials/:id/revoke | mint sk\_/pk\_ secrets, revoke credentials |
| GET /admin/jwks · POST /admin/jwks/rotate | keyring per env — required before the first token exchange |
| POST /admin/tickets | operator-minted enrollment tickets |
| POST /admin/users/:userId/recovery | operator-minted recovery codes (shown once) |
| GET /admin/audit · GET /admin/overview | audit events + counters |
| POST /admin/console-seed · POST /admin/demo-seed | bootstrap the console app / a demo relying party |

<a id="b-h-ids"></a>

## Identifier prefixes

| prefix | thing |
| --- | --- |
| 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 |

<a id="b-h-err"></a>

## 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).
