Sign-in¶
People sign in with a passkey and nothing else; there are no passwords. A passkey is bound to the address it was made at, so the ceremony runs on this server's own page in the browser, and the app collects the result with a one-time code bound to a PKCE challenge. An account gets its first passkey by signing up (where the operator allows it) or from a one-time ticket the operator issues; further passkeys from a ticket a signed-in person issues.
GET /passkey¶
The sign-in page
Unauthenticated
Callable with no credential.
The page every passkey ceremony runs on, opened in the system browser.
What it does is read from its address: mode=signin (the default) or
mode=signup, or a ticket to add a passkey to the account the
ticket names. An app passes its PKCE challenge and a state; when
the ceremony succeeds the page opens
revoked://auth?code=…&state=…, and the app redeems the code at
/api/passkeys/token.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
mode |
query | no | |
ticket |
query | no | |
challenge |
query | no | PKCE S256 challenge, base64url. |
state |
query | no |
Responses
| Status | Meaning |
|---|---|
200 |
The page. |
GET /app¶
Continue on the phone
Unauthenticated
Callable with no credential.
Where the QR code the app shows on a computer leads. It opens the app
(revoked://open) and, when the operator set APP_STORE_URL or
PLAY_STORE_URL, a download link for the phone it is opened on.
It names the server, so the app on the phone can be pointed at it.
Responses
| Status | Meaning |
|---|---|
200 |
The page. |
POST /api/passkeys/login/begin¶
Start a passkey sign-in
Unauthenticated
Callable with no credential.
Returns WebAuthn request options for a discoverable credential — no
account is named; the authenticator's answer says whose passkey it is.
Must be called at the server's own address (localhost on a
development machine, never a loopback IP). Rate-limited per IP.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
challenge |
string | The app's PKCE S256 challenge; the code issued at the end is bound to it. |
Responses
| Status | Meaning |
|---|---|
200 |
The ceremony, good for five minutes. |
400 |
passkey_request_invalid or passkey_origin_invalid. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
session |
string | |
options |
object | {publicKey: PublicKeyCredentialRequestOptions}, binary members base64url. |
POST /api/passkeys/login/finish¶
Finish a passkey sign-in
Unauthenticated
Callable with no credential.
Verifies the authenticator's assertion and returns a one-time code, good for two minutes, that only the holder of the PKCE verifier can redeem. A ceremony is answered once, right or wrong.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
session |
string | |
credential |
object | The PublicKeyCredential, binary members base64url. |
Responses
| Status | Meaning |
|---|---|
200 |
The one-time code. |
400 |
passkey_ceremony_invalid, passkey_request_invalid or passkey_origin_invalid. |
401 |
passkey_verification_failed, or passkey_unknown: no account on this server holds this passkey any longer (its account was deleted or the key removed), so a client can ask the password manager to drop it. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
code |
string | |
accepted |
object | What the account holds now, for the WebAuthn Signal API: a passkey removed from the account, or a changed address, then also leaves or changes in the password manager. |
POST /api/passkeys/register/begin¶
Start registering a passkey
Unauthenticated
Callable with no credential.
Either a new account — email, where the operator allows signups — or
a ticket, which adds a passkey to the account it names. Returns
WebAuthn creation options that require a discoverable credential and
user verification. Nothing is written until the ceremony finishes.
Where the operator asks new accounts to confirm their address
(SIGNUP_VERIFY_EMAIL), a new account also needs the proof from
/api/passkeys/register/verify. It is checked here and spent when the
ceremony finishes.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
email |
string | The new account's address. Ignored with a ticket. |
ticket |
string | A one-time ticket from /api/passkeys/tickets or the operator. |
name |
string | What the passkey is called in the owner's list. |
challenge |
string | The app's PKCE S256 challenge, when the result should sign an app in. |
proof |
string | The confirmed address, from /api/passkeys/register/verify. Required for a new account where the operator asks for confirmation. |
Responses
| Status | Meaning |
|---|---|
200 |
The ceremony, good for five minutes. |
400 |
passkey_email_invalid, passkey_ticket_invalid, passkey_request_invalid or passkey_origin_invalid. |
403 |
signups_disabled: no ticket, and this server does not accept registrations. email_verification_required: the address was not confirmed, or the proof is for another one. |
409 |
passkey_email_taken. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
session |
string | |
options |
object | {publicKey: PublicKeyCredentialCreationOptions}, binary members base64url. |
POST /api/passkeys/register/email¶
Send a code that confirms a new account's address
Unauthenticated
Callable with no credential.
Only where the operator asks new accounts to confirm their address
(SIGNUP_VERIFY_EMAIL). Mails a 6-digit code, good for ten minutes
and five guesses, replacing any earlier one. An address is sent at most
one code a minute and five an hour; each client is limited separately
(RATELIMIT_SIGNUP_EMAILS per hour).
An address that already has an account gets the same answer and the same limits, but its mail says that an account exists and carries no code. The endpoint does not tell anyone whether an address is registered.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
email |
string | |
locale |
string (en | de) |
Language of the mail; anything else sends English. |
Responses
| Status | Meaning |
|---|---|
200 |
Sent. |
400 |
passkey_email_invalid, passkey_request_invalid, or email_verification_off: this server does not confirm addresses. |
403 |
signups_disabled. |
429 |
email_code_too_soon, or rate_limited. |
502 |
email_send_failed: the mail server refused or could not be reached. |
Response fields
| Field | Type | Notes |
|---|---|---|
expiresAt |
string | |
resendAfter |
integer | Seconds until another code may be asked for. |
POST /api/passkeys/register/verify¶
Trade the mailed code for a proof
Unauthenticated
Callable with no credential.
The right code is spent and returns a proof of the address, good for
fifteen minutes, that /api/passkeys/register/begin then carries. A
wrong code costs one of its five attempts.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
email |
string | |
code |
string |
Responses
| Status | Meaning |
|---|---|
200 |
Confirmed. |
400 |
email_code_invalid: wrong, expired, spent, or guessed too often. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
proof |
string |
POST /api/passkeys/register/finish¶
Finish registering a passkey
Unauthenticated
Callable with no credential.
Verifies the attestation, then writes the passkey — and, for a signup, the account — and spends the ticket. Returns a one-time code when the ceremony was started with a PKCE challenge.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
session |
string | |
credential |
object | The PublicKeyCredential, binary members base64url. |
Responses
| Status | Meaning |
|---|---|
200 |
Saved. |
400 |
passkey_ceremony_invalid, passkey_verification_failed, passkey_ticket_invalid or passkey_origin_invalid. |
403 |
email_verification_required: the proof was already spent on another account, or expired. |
409 |
passkey_email_taken. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
code |
string | Present when a PKCE challenge was given. |
POST /api/passkeys/token¶
Exchange a code for a session (the app)
Unauthenticated
Callable with no credential.
Spends the one-time code — right or wrong, a code works once — and, when the verifier matches its challenge, returns a session token. Not needed for API-key access.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
code |
string | |
verifier |
string | The PKCE verifier. |
Responses
| Status | Meaning |
|---|---|
200 |
A session token and the user record. |
400 |
passkey_grant_invalid. |
401 |
two_factor_required: the account has an authenticator app. No session yet; the body also carries challenge and expiresAt, and POST /api/passkeys/token/2fa completes the sign-in. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
token |
string | |
record |
object | |
meta |
object |
POST /api/passkeys/token/2fa¶
Complete a sign-in with an authenticator code (the app)
Unauthenticated
Callable with no credential.
Completes a sign-in that POST /api/passkeys/token answered with
401 two_factor_required: the challenge from that answer and the
current 6-digit code of the account's authenticator app (TOTP, RFC
6238, one step of clock drift either way). A challenge lasts five
minutes and allows five codes; the account allows ten codes in five
minutes across all challenges.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
challenge |
string | |
code |
string |
Responses
| Status | Meaning |
|---|---|
200 |
A session token, the user record and the same meta as /api/passkeys/token. |
400 |
two_factor_challenge_invalid: unknown, expired, spent, or out of attempts. |
401 |
two_factor_code_invalid. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
GET /api/2fa¶
Two-factor status of the signed-in account
Auth: Session
Responses
| Status | Meaning |
|---|---|
200 |
The status. |
401 |
not_authenticated: no session, or an API key. |
Response fields
| Field | Type | Notes |
|---|---|---|
enabled |
boolean | |
required |
boolean | The server requires it (REQUIRE_2FA). |
setupRequired |
boolean | Required and not yet set up: the app asks for it before anything else. |
enabledAt |
['string', 'null'] |
POST /api/2fa/totp/setup¶
Start setting up an authenticator app
Auth: Session
Makes a new secret and keeps it pending until a code confirms it. The
secret is returned here once, as text and inside an otpauth:// URI
for a QR code; no other endpoint returns it.
Responses
| Status | Meaning |
|---|---|
200 |
The pending secret. |
401 |
not_authenticated. |
409 |
two_factor_already_enabled. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
secret |
string | Base32, 160 bits. |
otpauthUri |
string |
POST /api/2fa/totp/confirm¶
Turn on the authenticator app being set up
Auth: Session
Request body
application/json
| Field | Type | Notes |
|---|---|---|
code |
string |
Responses
| Status | Meaning |
|---|---|
200 |
The new status, as GET /api/2fa, plus token: turning it on ends every session of the account, the calling one included, so the caller continues with this one. |
400 |
two_factor_code_invalid, also for a code already used. |
401 |
not_authenticated. |
409 |
two_factor_already_enabled or two_factor_not_pending. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
DELETE /api/2fa/totp¶
Turn off the authenticator app
Auth: Session
Needs a current code. Refused while the server requires two-factor authentication.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
code |
string |
Responses
| Status | Meaning |
|---|---|
200 |
The new status, as GET /api/2fa. |
400 |
two_factor_code_invalid. |
401 |
not_authenticated. |
403 |
two_factor_enforced. |
409 |
two_factor_not_enabled. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
POST /api/passkeys/tickets¶
Issue a link to add a passkey
Auth: Session
Returns a one-time link, good for fifteen minutes, to the sign-in page where the caller's account can register another passkey — on this device or, opened elsewhere, on another. Users only: an API key cannot let itself in as the person behind it.
Responses
| Status | Meaning |
|---|---|
200 |
The link. |
401 |
Refused, with a named reason. |
Response fields
| Field | Type | Notes |
|---|---|---|
url |
string | |
expiresAt |
string |
DELETE /api/passkeys/{id}¶
Remove a passkey
Auth: Session
Removes one of the caller's passkeys; it stops signing in at once. The
last one cannot be removed. Passkeys are listed through
/api/collections/passkeys/records (name, created, last used — never
the key).
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
204 |
Removed. |
401 |
Refused, with a named reason. |
404 |
No such resource, or the caller may not see it. |
409 |
passkey_last. |