Authentication and profile

Login with Apple (Sign in with Apple)

POST/auth/apple

Public: no sign-in needed.

Client sends the Apple identity token; the server verifies it against Apple's public keys and logs the user in (creating the account on first sign-in). Returns the same { access_token, refresh_token, user } as OTP.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet. Login successful

Login with Google (Sign in with Google)

POST/auth/google

Public: no sign-in needed.

Client sends the Google ID token; the server verifies it with Google and logs the user in (creating the account on first sign-in). Returns the same { access_token, refresh_token, user } as OTP login.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet. Login successful

Verify OTP & Login

POST/auth/login

Public: no sign-in needed.

Any code sent to this address on this channel in the last 15 minutes works (the newest first), once. A wrong code: 401 INVALID_CODE with attemptsLeft ("That code didn't match. 4 tries left."). The 5th wrong try burns the code: 429 TOO_MANY_ATTEMPTS without retryAfterSeconds, ask for a new code. More than 20 wrong codes in an hour for the address lock code checks: 429 TOO_MANY_ATTEMPTS with retryAfterSeconds and unlockAt. A used or replaced code: 401 CODE_EXPIRED.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet. Login successful

Verify OTP and Login (Mobile Apps)

POST/auth/login-app

Public: no sign-in needed.

The app's twin of /auth/login: tokens come in the body. Send the channel's app key (X-App-Key) and X-Install-Id: a random id the app makes once per install (a UUID, or 16 to 64 random letters, digits, '-' or '_') and sends on every request. The session is then bound to that install, never to the IP or user agent: it survives Wi-Fi/cellular changes and OS updates, and its tokens are refused (401 INSTALL_MISMATCH) from any other install. Without the header the session is bound to nothing. Two answers: a session (access_token, refresh_token, user), or, when the account has an authenticator or a 2-step passkey, mfa_required: true with methods and a 5-minute pending_token to finish at /auth/mfa/totp, /auth/mfa/otp or /auth/mfa/passkey/verify (send the same X-Install-Id there). Errors: 401 INVALID_CODE (with attemptsLeft), 401 CODE_EXPIRED, 429 TOO_MANY_ATTEMPTS, 403 ACCOUNT_CLOSED (restore with restore_account: true), 400 INVALID_INSTALL_ID.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet. A session, or a second step to finish

Login with email + password (OTP alternative)

POST/auth/login-password

Public: no sign-in needed.

Logs in with a password. If the account has a second factor enrolled, no tokens are returned yet: the response is { mfa_required: true, methods, pending_token } and the client finishes with /auth/mfa/totp, /auth/mfa/otp or /auth/mfa/passkey/verify.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet. Login successful or OTP required

Finish a TOTP-protected login with an authenticator/backup code

POST/auth/login-totp

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is of type object.

Logout and revoke session

POST/auth/logout

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet. Logged out

Get current user profile

GET/auth/me

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet. User profile returned

Which login methods an email supports (password/totp/otp/passkey)

POST/auth/methods

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Complete login with the emailed OTP

POST/auth/mfa/otp

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Second-factor passkey: get options

POST/auth/mfa/passkey/options

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is of type object.

Second-factor passkey: verify and complete login

POST/auth/mfa/passkey/verify

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Complete login with an authenticator/backup code

POST/auth/mfa/totp

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Change the password or recovery key, step 2

POST/auth/opaque/credential/finish

Needs a signed-in user (Bearer token or access_token cookie).

Stores the new record. Changing the password signs out every other session.

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Change the password or recovery key, step 1

POST/auth/opaque/credential/start

Needs a signed-in user (Bearer token or access_token cookie).

Needs a recent sign-in (an OPAQUE sign-in counts for 10 minutes). Otherwise 401 STEP_UP_REQUIRED.

Request body application/json

Response

200. The payload in data is not described in the spec yet.

OPAQUE sign-in, step 2

POST/auth/opaque/login/finish

Public: no sign-in needed.

App tokens { account_id, access_token, refresh_token, expires_in } (rotate with /auth/refresh-app); 401 INVALID_CREDENTIALS. An enrolled authenticator or passkey still applies (mfa_required).

Parameters

Request body application/json

Response

200. The payload in data is of type object.

OPAQUE sign-in, step 1

POST/auth/opaque/login/start

Public: no sign-in needed.

credential = password | recovery. Unknown usernames get a well-formed fake response. 429 TOO_MANY_ATTEMPTS with retryAfterSeconds (and retry_after) after 10 failed sign-ins per username per hour.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet.

OPAQUE signup, step 2: create the account

POST/auth/opaque/register/finish

Public: no sign-in needed.

Stores the password and recovery records and signs in. Needs a solved proof-of-work, a Turnstile token when the channel asks, and at most 5 new accounts per IP per day. QA mode (dev only): a .test email proven by its code from the test inbox makes a QA account, counted against the shared QA quota instead of the per-IP limit and purged after 7 days.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet. { account_id, access_token, refresh_token, expires_in }

OPAQUE signup, step 1 (once per credential)

POST/auth/opaque/register/start

Public: no sign-in needed.

Checks the username is free in the channel and answers the OPAQUE registration request. Call it twice with the same username: once for the password, once for the recovery key.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Passkey login, step 1: get options

POST/auth/passkey/login/options

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is of type object.

Passkey login, step 2: verify the assertion and issue tokens

POST/auth/passkey/login/verify

Public: no sign-in needed.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Passkey registration, step 1: get options

POST/auth/passkey/register/options

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

Passkey registration, step 2: verify and store

POST/auth/passkey/register/verify

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

200. The payload in data is not described in the spec yet.

List the signed-in user's passkeys

GET/auth/passkeys

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

Remove one of the signed-in user's passkeys

DELETE/auth/passkeys/{id}

Needs a signed-in user (Bearer token or access_token cookie).

Parameters

Response

200. The payload in data is not described in the spec yet.

Proof-of-work challenge for a new OPAQUE account

GET/auth/pow

Public: no sign-in needed.

Stateless: { salt, bits, exp, sig }. Find a nonce so that sha256(salt ‖ nonce) has bits leading zero bits, then send { salt, bits, exp, sig, nonce } as pow to /auth/opaque/register/finish. Valid 10 minutes, one account per solution.

Response

200. The payload in data is of type object.

Update user profile details

PATCH/auth/profile

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

200. The payload in data is not described in the spec yet. Profile updated successfully

How many unused recovery codes remain (never the codes)

GET/auth/recovery-codes

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

Replace all recovery codes (needs a current authenticator code). The new codes are returned once.

POST/auth/recovery-codes

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Refresh authentication tokens (Web)

POST/auth/refresh

Public: no sign-in needed.

Response

200. The payload in data is not described in the spec yet. New tokens issued

Refresh authentication tokens (Mobile Apps)

POST/auth/refresh-app

Public: no sign-in needed.

Trade the refresh token for a new pair. Never bound to the IP or user agent. A session signed in with X-Install-Id needs that same header here (401 INSTALL_MISMATCH otherwise: sign in again, refreshing won't help). An older session refreshed with the header becomes bound to that install. 401 UNAUTHENTICATED: the refresh token is unknown, spent, revoked or older than 30 days.

Parameters

Request body application/json

Response

200. data is object (RefreshResultDto). New tokens issued

Request 6-digit OTP (Login/Register)

POST/auth/request-otp

Public: no sign-in needed.

Always answers 200 with the same body for any address: an unknown address, an existing account, an account with no saved mobile (delivery sms/whatsapp), a channel closed to new accounts and a blocked new address can't be told apart. A code is sent only when the address can sign in or sign up on this channel (signup policy, or a pending team invite there). The answer takes a minimum time (it follows the route's own speed) and does not wait for delivery. retryAfterSeconds says when Resend opens. Resend: 30 s after the first code, 60 s after the second, then 120 s, at most 5 codes per address and channel in 15 minutes (429 OTP_RATE_LIMIT_REACHED, reason cooldown or window). Every code sent stays valid for 15 minutes. Wider caps: per address across all channels (429 OTP_RECIPIENT_LIMIT), per IP, IPv6 by /64 network (429 OTP_IP_LIMIT) and per channel (429 OTP_CHANNEL_LIMIT). Every 429 carries the exact retryAfterSeconds and a Retry-After header. Parallel requests can't overshoot any of them.

Parameters

Request body application/json

Response

200. data is object (RequestOtpResultDto). Accepted. message is the same for every address; a code was sent if the address can sign in here.

Reset password using an OTP (forgot password)

POST/auth/reset-password

Public: no sign-in needed.

No current password needed. First call request-otp, then submit the code here with the new password.

Parameters

Request body application/json

Response

200. The payload in data is not described in the spec yet. Password reset successfully

The signed-in user's security log: sign-ins, failed attempts, password / two-factor / passkey changes, session sign-outs (paged, max 100)

GET/auth/security/activity

Needs a signed-in user (Bearer token or access_token cookie).

Parameters

Response

200. The payload in data is not described in the spec yet.

What protects the signed-in account: password set/changed, two-step methods, passkey and recovery-code counts (flags only)

GET/auth/security/summary

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

List all active sessions

GET/auth/sessions

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. data is object[].

Revoke a specific session

POST/auth/sessions/{id}/revoke

Needs a signed-in user (Bearer token or access_token cookie).

Parameters

Response

201. The payload in data is not described in the spec yet.

Sign out everywhere: revoke every session and refresh token except this one (step-up)

POST/auth/sessions/logout-all

Needs a signed-in user (Bearer token or access_token cookie).

Needs a step-up in the last 10 minutes (401 STEP_UP_REQUIRED until POST /auth/step-up). With linked_devices: true (alias e2ee_devices), every linked end-to-end-encrypted device of the account is removed too, except this session's own device; pending device-link tokens stop working. The devices of the revoked sessions stop getting push notifications. revoked_sessions counts only the sessions this call deleted (one removed by a refresh while it runs is skipped). Any value of linked_devices other than a boolean form is 400 VALIDATION_FAILED. A row that cannot be deleted gives 503 SIGN_OUT_INCOMPLETE (send it again).

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Sign out everywhere: revoke every session and refresh token except this one (step-up)

POST/auth/sessions/revoke-all

Needs a signed-in user (Bearer token or access_token cookie).

Needs a step-up in the last 10 minutes (401 STEP_UP_REQUIRED until POST /auth/step-up). With linked_devices: true (alias e2ee_devices), every linked end-to-end-encrypted device of the account is removed too, except this session's own device; pending device-link tokens stop working. The devices of the revoked sessions stop getting push notifications. revoked_sessions counts only the sessions this call deleted (one removed by a refresh while it runs is skipped). Any value of linked_devices other than a boolean form is 400 VALIDATION_FAILED. A row that cannot be deleted gives 503 SIGN_OUT_INCOMPLETE (send it again).

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Public: the bot check and sender address for a channel's sign-in pages

GET/auth/sign-in-options

Public: no sign-in needed.

Send the channel as x-ref. captcha is { provider: 'none' } or { provider: 'turnstile', sitekey }. When it is Turnstile, request-otp, login-password, login-totp and opaque/login/start need the widget's token as captcha. sender is the address sign-in codes come from.

Parameters

Response

200. The payload in data is not described in the spec yet.

Whether this session has confirmed it's you in the last 10 minutes, and the ways it can

GET/auth/step-up

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

Confirm it's you (passkey, authenticator, password or e-mailed code); lasts 10 minutes for this session

POST/auth/step-up

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

200. The payload in data is not described in the spec yet.

E-mail a 6-digit confirmation code to the account's own address

POST/auth/step-up/email

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

End the confirmation early

POST/auth/step-up/end

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

Confirm it's you with the account's password (OPAQUE), step 2

POST/auth/step-up/opaque/finish

Needs a signed-in user (Bearer token or access_token cookie).

Steps up THIS session for 10 minutes, as every step-up method does, and answers the GET /auth/step-up status. No new session and no tokens. If the account has an authenticator, passkey or e-mail codes, nothing is granted yet: the answer is { active: false, mfa_required: true, methods, expires_in: 300 } and the client finishes at /auth/step-up/opaque/second-factor. 401 INVALID_CREDENTIALS for a wrong password and for an expired, used or foreign login_id; 429 TOO_MANY_ATTEMPTS. Recorded as step_up_opaque (failures as step_up_failed, or login_locked at the limit).

Request body application/json

Response

200. The payload in data is of type object.

Confirm it's you with the password (OPAQUE), the second factor

POST/auth/step-up/opaque/second-factor

Needs a signed-in user (Bearer token or access_token cookie).

Only after /auth/step-up/opaque/finish answered mfa_required, within 5 minutes, on the same session and client. method = one of its methods: totp (authenticator or recovery code), passkey (assertion for POST /auth/step-up/passkey/options) or email (code from POST /auth/step-up/email). A wrong code can be retried until the step-up lockout; success steps up this session for 10 minutes, once. Errors as at /auth/mfa/*: 401 INVALID_CODE, INVALID_CREDENTIALS (passkey, other client), CODE_EXPIRED (nothing pending, or already used), 400 FACTOR_NOT_AVAILABLE, 429 TOO_MANY_ATTEMPTS.

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Confirm it's you with the account's password (OPAQUE), step 1

POST/auth/step-up/opaque/start

Needs a signed-in user (Bearer token or access_token cookie).

The OPAQUE login exchange for the signed-in account (the username comes from the session, never the body). credential = password (default) | recovery. Answers { login_id, login_response }; login_id lives 2 minutes, works once, and only for this session from this client. The same lockout as sign-in: 429 TOO_MANY_ATTEMPTS after 10 failed tries an hour, sign-in and step-up together. 400 STEP_UP_METHOD_UNAVAILABLE when the account has no such credential; 404 METHOD_DISABLED when its channel turned OPAQUE off.

Request body application/json

Response

200. The payload in data is not described in the spec yet. { login_id, login_response }

Passkey challenge to confirm it's you

POST/auth/step-up/passkey/options

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is of type object.

Stage 2: Switch active profile/business and get new tokens (Web)

POST/auth/switch-business

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

201. The payload in data is not described in the spec yet.

Stage 2: Switch active profile/business/channel (Mobile/CRM Apps)

POST/auth/switch-business-app

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

201. The payload in data is not described in the spec yet.

Stage 2: Switch active profile/business/channel (Mobile/CRM Apps)

POST/auth/switch-channel

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

201. The payload in data is not described in the spec yet.

Stage 2: Switch active profile/business and get new tokens (Web)

POST/auth/switch-profile

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

201. The payload in data is not described in the spec yet.

Stage 2: Switch active profile/business/channel (Mobile/CRM Apps)

POST/auth/switch-profile-app

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

201. The payload in data is not described in the spec yet.

Disable authenticator (TOTP) two-factor

POST/auth/totp/disable

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Confirm a code to enable TOTP; returns backup codes

POST/auth/totp/enable

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

200. The payload in data is not described in the spec yet.

Start authenticator (TOTP) setup; returns a QR code

POST/auth/totp/setup

Needs a signed-in user (Bearer token or access_token cookie).

Response

200. The payload in data is not described in the spec yet.

Enable/disable two-factor authentication

PATCH/auth/two-factor

Needs a signed-in user (Bearer token or access_token cookie).

Request body application/json

Response

200. The payload in data is not described in the spec yet. Two-factor preference updated