Skip to content

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.