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
| 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
| 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 |
POST /v1/accounts:sendSignUpLink
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
| 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
| 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.
| 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.
| 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
| 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
| 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 |