Account API
Every environment serves an API for its users’ own accounts at {issuer}/account/v1. It is what an app’s settings page calls, through the settings components of auth-react, the account clients of auth-js, or a web client’s backend. See Account settings for how to build the page.
Calling it
Section titled “Calling it”- Token: the user’s access token for the account API:
audmust beaccount. That is the audience of a token whose client names no other API; otherwise ask for one withresource=accounton a refresh. A token for one of your APIs, an ID token and a machine client’s token are refused. - Scheme:
Authorization: Bearer <token>, or for a DPoP-bound tokenAuthorization: DPoP <token>with aDPoPproof (htu{issuer}/account/v1/…, without the query string;aththe token’s hash). - Session: every request checks that the token’s session is still active. A session that has ended gets
401from every route at once, even though its access token has not expired. - CORS: answered for the origins of the environment’s clients, and for
localhostin development. No cookies are involved. - Bodies: JSON. A body that is not valid JSON is answered
400, a missing JSON content type415, and a missing or mistyped field422, as plain text.
Every failure of the token (missing, expired, wrong audience, a bad or replayed proof) is 401 token_invalid with WWW-Authenticate: Bearer error="invalid_token". Other errors have the API error shape, { "code", "message" }.
A fresh login
Section titled “A fresh login”Changes that would let someone who borrowed the device keep the account need a recent login:
- the user proved who they are in the last 600 seconds (
auth_time), - if they have a second factor (an authenticator app or a passkey), the session is at
aal2, and - that login (or step-up) was made at the client the token was issued to.
A refresh does not make a session fresh, and neither does single sign-on: a token another app of the group gets from the same session without a prompt carries the same auth_time, but the user did not just log in there, so that app is asked for a step-up (with max_age="0") before it may change the account. A session a session ticket carried into another browser is a fresh login for no app until the user proves a factor there. Otherwise the answer is 401 step_up_required, which says what to ask for in the header and in the body:
HTTP/1.1 401 UnauthorizedWWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="aal2", max_age="600"Content-Type: application/json
{ "code": "step_up_required", "message": "A more recent or stronger login is required", "acr_values": "aal2", "max_age": 600}acr_values is there only when the user has a second factor (it is null in the body otherwise). The client then asks for a new login of the same session with max_age=0 (and acr_values=aal2 when named) and tries again; auth-react’s withStepUp does exactly that. See Two-step login.
Routes
Section titled “Routes”| Route | Fresh login |
|---|---|
GET /profile |
no |
PATCH /profile |
no |
POST /password |
yes |
DELETE /password |
yes |
POST /email |
yes |
POST /email/confirm |
yes |
POST /totp |
yes |
POST /totp/confirm |
yes |
DELETE /totp |
yes |
POST /recovery-codes |
yes |
GET /passkeys |
no |
POST /passkeys/options |
yes |
POST /passkeys |
yes |
PATCH /passkeys/:id |
no |
DELETE /passkeys/:id |
yes |
GET /identities |
no |
POST /identities/link |
yes |
POST /identities/link/confirm |
no |
DELETE /identities/:id |
yes |
GET /sessions |
no |
DELETE /sessions/:id |
for another session than the token’s |
DELETE /me |
yes |
Paths are relative to /account/v1. There is no route that ends every session at once; changing the password or the email address does, for all but the current one, and so does turning on two-step login (the first authenticator app or passkey).
Whatever changes the ways in or the second step of an account (a new password or address, an authenticator app, a passkey or a provider added or removed, new recovery codes) also ends the logins that are under way for it: a login that had passed its first step before the change is answered invalid_session at its next one, and starts again.
Profile
Section titled “Profile”Read the profile
Section titled “Read the profile”{ "id": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10", "email_verified": true, "phone": null, "name": "Ada", "picture": null, "created_at": "2026-10-28T09:12:44Z", "has_password": false, "has_totp": false, "passkeys": 0, "recovery_codes_left": 0}passkeys is a count, and recovery_codes_left the number of unused recovery codes.
Change the name or picture
Section titled “Change the name or picture”| Field | Rules |
|---|---|
name |
Trimmed; at most 100 characters, no control characters. |
picture |
An https URL of at most 500 bytes. |
Both are written on every call: a field that is left out, or empty, is cleared. Send both to change one. The answer is the profile; user.updated is recorded.
Password
Section titled “Password”Set or change the password
Section titled “Set or change the password”{ "new_password": "a long enough password" }No current password is asked: the fresh login stands for it. Answers 204.
- The environment must have password login enabled (else
400“password login is not enabled”), and the user an email address to log in with. - The password must be 15 to 64 characters, or 8 to 64 in an environment that requires two-step login, and must not appear in a known data breach (
400with the reason). - Every other session of the user ends, with its tokens; the current one stays.
password.changedis recorded and the user gets an email.
Remove the password
Section titled “Remove the password”Answers 204, or 404 without a password. Refused with 409 “this is your only way to log in” unless another way remains: email codes enabled with an address, a provider or wallet linked, or a passkey. The user gets an email.
Email address
Section titled “Email address”Change the email address
Section titled “Change the email address”Answers 202 with no body, and emails a six-digit code to the new address, good for 10 minutes. The address is normalised (trimmed, lowercased) and must follow the environment’s address rules: a +tag or a throwaway domain can be refused there (400 with the reason).
The answer is the same whether or not the address is taken; an address someone else has gets no code. A new request replaces a pending one.
Confirm the new address
Section titled “Confirm the new address”{ "code": "482913" }A wrong or expired code is 400 “that code is not right or has expired”; a code allows five attempts, and its answers count on the new address’s answers to email codes for the day (Rate limits). Once those are spent, the right code is not accepted either: it ends, and the answer is 400 “that code was right, but codes for this address are paused for up to a day after too many wrong tries; ask for a new one later”. On success every other session ends, as for a password change, email.changed is recorded, and the old address is told of the change.
Authenticator app
Section titled “Authenticator app”Start an authenticator app
Section titled “Start an authenticator app”{ "secret": "JBSWY3DPEHPK3PXP…", "otpauth_uri": "otpauth://totp/…?secret=…&issuer=…&algorithm=SHA1&digits=6&period=30", "enrollment_token": "Zm9v…"}Nothing is saved yet. The URI’s label is the app group’s name and the user’s address (or account), and its issuer the group’s name. Show it as a QR code (or the secret for typing in); the enrollment_token carries the secret, sealed, for 10 minutes. TOTP is SHA-1, six digits, 30 seconds. 409 when the user already has one.
Confirm the authenticator app
Section titled “Confirm the authenticator app”{ "enrollment_token": "Zm9v…", "code": "123456" }{ "recovery_codes": ["ABCDE-FGHIJ", "KLMNO-PQRST", "…"] }The code must be the current one (one step either way is accepted). The answer has ten recovery codes, shown this once: XXXXX-XXXXX from A–Z and 2–7. A wrong code or an expired setup is 400. mfa.enrolled is recorded and the user gets an email.
When this is the user’s first second factor, every other session of the user ends, with its tokens, as when the password changes; the current one stays. A session made before there was a second step never passed one. Your other apps and the user’s other devices see their next refresh refused (invalid_grant) and log the user in again, now with the second step; the email says that other devices were logged out.
Remove the authenticator app
Section titled “Remove the authenticator app”Answers 204, or 404. In an environment that requires two-step login it is refused (409) unless the user has a passkey. Without a passkey left, the recovery codes go too. mfa.removed is recorded.
Make new recovery codes
Section titled “Make new recovery codes”Answers { "recovery_codes": [ten codes] } and the old set stops working. Needs an authenticator app or a passkey first (400). There is no route that counts them: recovery_codes_left in the profile does.
Passkeys
Section titled “Passkeys”List passkeys
Section titled “List passkeys”{ "passkeys": [ { "id": "8c1d…", "name": "MacBook", "created_at": "2026-10-30T18:02:11Z", "last_used_at": null, "backed_up": true, "transports": ["internal", "hybrid"] } ], "rp_id": "your-app.com", "max": 10}rp_id is the environment’s passkey domain (null when it has none), and max the most passkeys a user may have.
Start adding a passkey
Section titled “Start adding a passkey”Answers { "options": …, "registration_token": … }: WebAuthn creation options for navigator.credentials.create (a discoverable credential with user verification, no attestation, algorithms ES256, EdDSA and RS256, the user’s existing passkeys excluded, a five-minute timeout) and a token that carries the challenge for 10 minutes. 409 when the environment has no passkey domain, or the user has 10 passkeys.
Add a passkey
Section titled “Add a passkey”{ "registration_token": "…", "credential": { "id": "…", "rawId": "…", "type": "public-key", "response": { "clientDataJSON": "…", "attestationObject": "…" } }, "name": "MacBook" }credential is the browser’s answer in its JSON form; name is optional (at most 60 characters, Passkey by default). Answers 201:
{ "passkey": { "id": "8c1d…", "name": "MacBook", "created_at": "…", "last_used_at": null, "backed_up": true, "transports": ["internal", "hybrid"] }, "recovery_codes": ["…"] }recovery_codes comes only when this is the user’s first second factor; every other session of the user ends then too, as for the authenticator app. The ceremony must come from a page of the environment on the passkey domain or under it; otherwise, or when the setup expired, 400. A passkey that is already registered is 409. See Passkeys.
Rename a passkey
Section titled “Rename a passkey”{ "name": "Work laptop" }. Answers 204, or 404.
Remove a passkey
Section titled “Remove a passkey”Answers 204, or 404. The last second factor cannot go in an environment that requires two-step login (409); when the last one goes, so do the recovery codes.
Linked providers
Section titled “Linked providers”List linked providers
Section titled “List linked providers”{ "identities": [ { "id": "…", "provider": "email", "subject": "[email protected]", "email": "[email protected]", "name": null, "created_at": "…", "last_used_at": "…" }, { "id": "…", "provider": "github", "subject": "77", "email": "[email protected]", "name": "Octo", "created_at": "…", "last_used_at": null } ]}email and name are what the provider said when the identity was linked.
Unlink a provider
Section titled “Unlink a provider”Answers 204. The email identity cannot be unlinked (change the address instead), and neither can the user’s only identity (409). identity.unlinked is recorded.
Linking a provider
Section titled “Linking a provider”Linking a social or custom provider to the signed-in account takes three steps, and nothing is stored between them.
1. Start. The page asks for the provider’s address:
{ "provider": "github", "return_to": "https://app.your-app.com/settings?tab=logins" }{ "url": "https://github.com/login/oauth/authorize?…&state=link.…" }- The provider must be enabled in the environment and have credentials (
400otherwise). return_tois anhttp(s)address of at most 200 characters on an allowed origin of the token’s client (orlocalhostin development); otherwise403 origin_not_allowed. Its fragment is dropped.- An account that already has that provider gets
409.
2. The provider. The browser goes to url. The provider returns to the same /callback/{provider} a login uses; the page shown there asks “Add this {Provider} login?” and names the account it will be added to. Its button goes to return_to#link_code=…; “This is not my account” goes to return_to#link_error=cancelled, and a provider error to #link_error=provider_error. The attempt is good for 10 minutes.
3. Confirm. The page, signed in as the same user, sends the code:
{ "link_code": "…" }{ "identity": { "id": "…", "provider": "github", "subject": "77", "email": "[email protected]", "name": "Octo", "created_at": "…", "last_used_at": null } }Answers 201. The link step’s address can be sent to anyone, so the code counts only in a request of the user who started it: from another account it is 400 “that link was started from another account”. A provider account that belongs to someone else is 409; the same code twice returns the identity again. identity.linked is recorded and the user gets an email. A provider’s address never replaces the account’s own.
auth-react’s <LinkedAccounts /> runs all three steps; see the component.
Sessions
Section titled “Sessions”List sessions
Section titled “List sessions”{ "sessions": [ { "id": "5d2c…", "current": true, "aal": 1, "amr": ["email"], "ip": "203.0.113.7", "user_agent": "Mozilla/5.0 …", "created_at": "…", "last_seen_at": "…" } ]}The user’s active sessions, last used first; current marks the one the token belongs to.
End a session
Section titled “End a session”Ends one of the user’s sessions and its tokens: that device’s next refresh is refused. Answers 204; another user’s session is 404. session.revoked is recorded with the reason account.
Ending the session the token itself comes from is a logout and needs nothing more. Ending any other session needs a fresh login (401 step_up_required otherwise), like every change to what guards the account: a session left signed in somewhere must not be able to log the account’s owner out of the device they are at.
Delete the account
Section titled “Delete the account”Deletes the signed-in user’s account at once and for good: there is no window in which it can be undone. DELETE /account/v1, the route’s old address, does the same. Answers 204; the next request with the token is 401, and so is the next refresh, on every device.
What goes, in one transaction:
- the user, their identities, password, authenticator app, recovery codes and passkeys, their sessions, refresh tokens and codes, their consents, their place in each app and their roles;
- the network identifiers (address, user agent, device, browser and system) of every audit event the user did or that was done to them; the events themselves stay, with the bare user id, for as long as the audit log is kept;
- the
userobject of every webhook delivery about them, sent or still to be sent, in the endpoints’ 30-day log; - every email to their address in the environment’s queue, sent or not.
user.deleted is recorded (its webhook has user: null and data.by "user"), and a last email goes to the address that was deleted: the account is gone, what that means (signing up again with the address makes a new, empty account), and whom to write to with a question about their data. It speaks in the name of the app group, as the other emails of this API do. Your app’s own data about the user is yours to delete when the webhook arrives. See Data and retention for what is kept and for how long.
Developer accounts
Section titled “Developer accounts”On the platform environment, the one the dashboard logs developers in to, the account is a developer’s, and a workspace cannot be left without an owner. While the developer is the only owner of any workspace the answer is 409 sole_owner, and nothing is deleted:
{ "code": "sole_owner", "message": "You are the only owner of Acme. Make another member an owner, or delete the workspace, first.", "workspaces": [{ "id": "…", "name": "Acme" }]}Another owner counts only while their own account exists. Otherwise, with the account, the developer leaves every workspace: their memberships go, the API keys they made are deleted, and the invitations they sent and that were not answered yet are deleted (an invitation can be accepted only while its sender could still grant its role), as are the invitations to their address. The LinkPay subscriptions they pay for (paid through a checkout they opened, which the subscription names) stop renewing first, or, while the first payment of one is still being made, as soon as it can be; when LinkPay does not answer, the answer is 502 upstream_error and nothing is deleted. Their address is cleared from the subscriptions of the workspaces they paid for, and from the platform’s invitation events; the changes they made in their workspaces’ environments lose where they were made from, right after, in batches. See Data and retention.
Events
Section titled “Events”| Route | Event | Email to the user |
|---|---|---|
PATCH /profile |
user.updated |
|
POST /password |
password.changed |
yes |
DELETE /password |
password.removed (not a webhook) |
yes |
POST /email/confirm |
email.changed, also sent as user.updated |
to the old address |
POST /totp/confirm, POST /recovery-codes, POST /passkeys |
mfa.enrolled |
yes |
DELETE /totp, DELETE /passkeys/:id |
mfa.removed |
yes |
POST /identities/link/confirm |
identity.linked |
yes |
DELETE /identities/:id |
identity.unlinked |
|
DELETE /sessions/:id |
session.revoked |
|
DELETE /me |
user.deleted |
to the deleted address |
The emails speak in the name of the app group.
Rate limits
Section titled “Rate limits”Every route that adds to what guards the account is limited per session, and the other writes per user (never per address: a web client’s backend sends every user’s calls from one address). Per session, so that somebody else signed in to the account spends their own session’s limit and never what its owner needs to put them out. What only takes access away is not limited.
| Route | Limit |
|---|---|
The routes that need a fresh login and add something (except the two that only start a setup, POST /totp and POST /passkeys/options, and the two below), and POST /identities/link/confirm |
30 an hour per session, all of them together |
DELETE /password, DELETE /totp, DELETE /passkeys/:id, DELETE /identities/:id, DELETE /sessions/:id |
none (they need a fresh login all the same, except ending the token’s own session) |
POST /password |
Also 10 new passwords per session in 10 minutes |
POST /email |
10 codes per session in 15 minutes, 3 of them to one domain that is not a public provider’s; 10 per inbox across all environments. |
POST /email/confirm |
10 attempts per session in 10 minutes, and 5 per code. |
PATCH /profile, PATCH /passkeys/:id |
120 an hour per user |
A route that needs a fresh login counts a call only once it has shown one.
Over a limit: 429 rate_limited with Retry-After. See Rate limits.
From a web client’s backend
Section titled “From a web client’s backend”A web client keeps tokens on its server, so its page calls the account API through the backend: the Rust SDK’s web client forwards {backend}/account/* to {issuer}/account/v1/* with an account token. It passes on the status and the JSON body only, not WWW-Authenticate or Retry-After; the step_up_required body still carries acr_values and max_age. Deleting the account is DELETE {backend}/account/me: once it is done, the backend also ends the user’s sessions at that client, and its answer clears the session cookie. See auth-client.