Skip to content

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.

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.

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 PATCH writes both the name and the picture. Send both, or the one left out is cleared. The picture is an https URL.
  • 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_limited with Retry-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.

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 Unauthorized
WWW-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.

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 />:

  1. 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.
  2. Delete account opens a dialog that asks them to type their email address (any capitals, spaces around it are fine), or confirmWord (DELETE by default) when the account has none, such as a wallet login. Until it matches, nothing can be pressed.
  3. 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_required and the login modal asks them to prove it is them; the deletion is then asked once more. With stepUp='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.
  4. The account is deleted, they are signed out in this browser (and every session of the account ends everywhere), and onDeleted runs: 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, with user: null and user_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 out
await useAuthStore.getState().deleteAccount()

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.

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.