Skip to content

API reference: auth

Signing in and signing up, which share one flow, and passkey sign-in, recovery with the recovery key, and ending a session. Every key is derived in the browser: these operations carry only derived auth keys and wrapped key material.

POST /v1/accounts

Creates an account and opens a session. Needs no session.

By handle, or by the token of a sign-up link, which makes the account with its address verified. An email address as identifier is refused.

Request body, application/json: RegisterRequest

Responses
Status Description Body
201

Account created, and a session opened.

SessionResponse application/json
400

Invalid request, or a used or expired sign-up link

Problem application/problem+json
409

Identifier already taken

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/accounts:lookupAuthParams

Says whether a handle has an account, with its KDF parameters; every address says it has one. Needs no session.

Throttled per address and per identifier. An email address answers alike whether or not an account has it, so the lookup never says who signed up: one with none answers parameters derived from a key the server keeps, the same on every call.

Request body, application/json: AuthParams

Responses
Status Description Body
200

Whether the account exists, and its KDF parameters.

KdfParams application/json
400

The request is malformed

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

Mails a sign-up link to an address, or, if it already has an account, a notice instead. Needs no session.

Always 202 with no body: both cases do the same work, so neither answers which it was.

Request body, application/json: SignUpLinkRequest

Responses
Status Description Body
202

A link or a notice is on its way to the address

400

The request is malformed

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Sign-up emails used

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/sessions

Signs in with the password-derived auth key. Needs no session.

Attempts are limited per client address and identifier together. Failures are also counted per identifier from every address: after 20, one more is accepted each 45 seconds, and this answers 429 with Retry-After until then, whether or not an account has the identifier. Passkey and recovery-key sign-in are not held by that count.

Request body, application/json: LoginRequest

Responses
Status Description Body
201

Session opened.

SessionResponse application/json
400

The request is malformed

Problem application/problem+json
401

Authentication failed

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many attempts from this address, or failures for this identifier

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

DELETE /v1/sessions/current

Ends the current session. Needs a session.

Responses
Status Description Body
204

Session ended

401

No valid session token

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/sessions:beginPasskey

Starts a passkey sign-in. Needs no session.

It takes and reads nothing, so every caller gets the same answer.

Responses
Status Description Body
200

Sign-in challenge.

SignInChallenge application/json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

Too many ceremonies under way

Problem application/problem+json

POST /v1/sessions:finishPasskey

Finishes a passkey sign-in, opening a session. Needs no session.

Request body, application/json: SignInFinish

Responses
Status Description Body
201

Session opened.

PasskeySession application/json
400

The request is malformed

Problem application/problem+json
401

Refused

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/sessions:recover

Signs in with the recovery auth key. Needs no session.

The client then rewraps and changes the password.

Request body, application/json: RecoverRequest

Responses
Status Description Body
201

Session opened.

SessionResponse application/json
400

The request is malformed

Problem application/problem+json
401

Authentication failed

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json