Account settings for your users
Every environment has an account API that a signed-in user calls for their own account. Your app’s settings page is built on it: either with auth-react’s ready-made components, or with calls of your own. Nothing here needs your backend or the management API; each user can only ever reach their own account.
The components
Section titled “The components”auth-react has four components for a settings page. Put them anywhere inside <AuthProvider>:
import { DeleteAccount, LinkedAccounts, Passkeys, TwoStep } from '@seek-services/auth-react'
export function SecuritySettings() { return ( <section> <h2>Security</h2> <TwoStep /> <Passkeys /> <LinkedAccounts /> <DeleteAccount> <p>Your projects are deleted with your account.</p> </DeleteAccount> </section> )}| Component | Hook | What the user does there |
|---|---|---|
<TwoStep /> |
useTwoStep() |
Set up an authenticator app (with a QR code), remove it, make new recovery codes. |
<Passkeys /> |
usePasskeys() |
Add, rename and remove passkeys. Shows why passkeys cannot be added when they cannot (no WebAuthn, no passkey domain, a page off that domain, the limit of 10). |
<LinkedAccounts /> |
useIdentities() |
See the logins linked to the account, link another provider, unlink one. |
<DeleteAccount /> |
deleteAccount() of useAuthStore |
Delete the account, after reading what that means in your app and typing their email address. See below. |
The hooks give the same data and actions for a UI of your own. All four work for single-page apps and for web clients alike. Everything they change asks for a recent login first, as below.
What a user can change
Section titled “What a user can change”| Change | Account API | Fresh login | The user is told |
|---|---|---|---|
| Name and picture | PATCH /account/v1/profile |
no | |
| Set or change the password | POST /account/v1/password |
yes | by email |
| Remove the password | DELETE /account/v1/password |
yes | by email |
| Change the email address | POST /account/v1/email, then POST /account/v1/email/confirm |
yes | the old address, by email |
| Authenticator app | POST /account/v1/totp, POST /account/v1/totp/confirm, DELETE /account/v1/totp |
yes | by email |
| New recovery codes | POST /account/v1/recovery-codes |
yes | by email |
| Passkeys | POST /account/v1/passkeys/options, POST /account/v1/passkeys, PATCH and DELETE /account/v1/passkeys/:id |
yes, except renaming | by email |
| Link or unlink a provider | POST /account/v1/identities/link, …/link/confirm, DELETE /account/v1/identities/:id |
yes, except confirming | by email when linking |
| Sign out another device | GET /account/v1/sessions, DELETE /account/v1/sessions/:id |
no | |
| Delete the account | DELETE /account/v1/me |
yes | by email, once it is gone |
The details of every route, its body and its errors are in the account API reference. A few rules worth knowing before you build on them:
- Profile: a
PATCHwrites both the name and the picture. Send both, or the one left out is cleared. The picture is anhttpsURL. - Password: needs the password login method to be enabled, and an email address to log in with. It is checked like a new password at sign-up (length, and against known breaches). Changing it ends every other session of the user. It can be removed only while the user has another way in.
- Email: the new address gets a 6-digit code that lasts 10 minutes and takes 5 tries. The answer is the same whether or not the address belongs to someone else (then no code is sent), so nobody learns who has an account. The environment’s address rules apply (Bot protection). Confirming ends every other session and tells the old address.
- Two-step login: confirming an authenticator app returns 10 recovery codes, shown once; adding a first passkey does too. Making new codes replaces the old ones. Where the environment requires two-step login, the last second factor cannot be removed. Turning two-step login on (the first authenticator app or passkey) ends every other session of the user, as a new password does: they were signed in without a second step. The session that turned it on stays.
- Limits: these changes are counted per user, 30 an hour together, and other writes 120 an hour (Rate limits). Over a limit the answer is
429 rate_limitedwithRetry-After. - Linking: see linking a provider. The address it returns to must be on one of the client’s allowed origins.
- Deleting the account removes it at once, with its sessions and tokens; your webhooks get
user.deleted. See below.
A fresh login for changes
Section titled “A fresh login for changes”Changes to how someone logs in need a login from the last 10 minutes, with a second factor if the user has one (acr aal2). An older session gets:
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 }A refresh does not make a session fresh; only proving a factor again does. In the SDK the answer is a StepUpRequiredError, and withStepUp asks for exactly that login in the modal and runs the change again:
import { errorFromResponse } from '@seek-services/auth-js'import { authFetch, withStepUp } from '@seek-services/auth-react'
const issuer = 'https://your-app.auth.dev.seek.services'
async function setPassword(newPassword: string) { const res = await authFetch(`${issuer}/account/v1/password`, { method: 'POST', resource: 'account', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ new_password: newPassword }), }) // a step_up_required answer becomes a StepUpRequiredError if (!res.ok) throw errorFromResponse(res, await res.json().catch(() => null))}
await withStepUp(() => setPassword(newPassword))The components do this for every change they make. authFetch resolves with any status, so turn a refusal into an error yourself, as above; the auth-js clients (passkeys, twoStep, identities) throw StepUpRequiredError on their own.
Deleting the account
Section titled “Deleting the account”A user can delete their own account, at once: there is no undo window. <DeleteAccount /> is the ready UI, and deleteAccount() of useAuthStore (or auth-js’s AuthClient.deleteAccount()) the call behind it.
What the user sees with <DeleteAccount />:
- A panel that says the account goes at once with its profile, ways to log in and sessions, and then your own words in
children: what deleting means in your app (what goes with it there, what you keep because the law requires it, what to download or cancel first). SeekAuth only knows its side; the rest is yours to say. - Delete account opens a dialog that asks them to type their email address (any capitals, spaces around it are fine), or
confirmWord(DELETEby default) when the account has none, such as a wallet login. Until it matches, nothing can be pressed. - If their login is older than 10 minutes, or below their highest level (they have a second factor and the session did not use it), the server answers
step_up_requiredand the login modal asks them to prove it is them; the deletion is then asked once more. WithstepUp='redirect'they go to the hosted login page instead and come back to your redirect URI, where the panel opens its confirmation again for them to finish. - The account is deleted, they are signed out in this browser (and every session of the account ends everywhere), and
onDeletedruns: send them to a page that says it is done.
Every text of the panel and its dialog can be given in your app’s language with labels (the ones left out stay English; type a full translation as DeleteAccountLabels to have the compiler ask for every key). See <DeleteAccount />.
A refusal stays in the dialog with the server’s words (or yours, from labels.refusal), and the user stays signed in. The server answers 204 and then:
- sends a confirmation to the address that was deleted, in the environment’s name: the account is gone, what that means, and whom to write to;
- deletes the account with its identities, credentials, sessions and tokens, and cleans what it leaves behind elsewhere (see Data and retention);
- tells your webhooks
user.deleted, withuser: nullanduser_id. That is your backend’s cue to erase or anonymise its own copy of the user, and, with a web client, to end their sessions there (WebClient::end_sessions_of).
A web client deletes through its backend like any other account call: the page asks DELETE {backend}/account/me, which WebClient’s router passes on to DELETE /account/v1/me with a token for the account audience. When the answer is a success, the backend ends that user’s sessions at the client and clears the session cookie in the same answer, so the logout deleteAccount() sends afterwards finds nothing left to end. Nothing needs adding to the backend beyond the router it already mounts.
import { useAuthStore } from '@seek-services/auth-react'
// your own UI: the store goes through the step-up and signs the user outawait useAuthStore.getState().deleteAccount()Calling the account API yourself
Section titled “Calling the account API yourself”The account API is on the issuer host, under /account/v1, and takes an access token for the account audience, sent the way the client’s tokens are sent (with a DPoP proof from a single-page app). From a single-page app, authFetch(url, { resource: 'account' }) gets and sends such a token; it is the client’s default token already when the client has no default API. The API answers cross-origin requests from the environment’s allowed origins (and from localhost in development).
From a web client, the page calls its own backend instead: WebClient serves /auth/account/* and passes each call on to /account/v1/* with a token for the account audience. So authFetch('/auth/account/profile') reads the profile. The backend passes on the status and the body but not the WWW-Authenticate header, so withStepUp then asks for a fresh login (max_age=0) rather than a second factor in particular; the server asks only for what is missing.
Limits
Section titled “Limits”Sending email-change codes is limited per user (10 every 15 minutes), per address and per inbox; confirming one is limited per user too. Over a limit the answer is 429 rate_limited with Retry-After. See Rate limits.