Skip to content

How a login works

A login has two doors, and both lead through the same steps on the server: the same methods, the same rules for sign-up, second factors, terms and access, and the same tokens at the end.

Embedded login Hosted page
Where it shows A dialog on your own page SeekAuth’s page on the issuer host, in your app’s look
Endpoint POST /authorize-challenge, one call per step GET /authorize, a redirect there and back
Who drives it The SDK: login() in auth-react, beginLogin() in auth-js The browser
Clients First-party spa, web and native clients Every spa, web and native client, including any OpenID Connect library
Social providers Always leave through the hosted page’s redirect Redirect to the provider and back
Already signed in The page keeps its own session, with its refresh token A session cookie on the issuer host answers without a page
The embedded loginThe page calls POST /authorize-challenge with its client id and a PKCE challenge. SeekAuth answers 403 with a challenge to show, such as identify, email_code or mfa, and the page sends one step per call until SeekAuth answers 200 with an authorization code, good once for 60 seconds. The page exchanges it at POST /token with the PKCE verifier and a DPoP proof, and gets an access token, an ID token and a refresh token bound to its DPoP key. It calls your API with the access token and a fresh proof; the API verifies the token offline with the issuer’s published keys.Your pagethe SDK in the browserSeekAuththe environment’s issuerYour APIyour backendPOST /authorize-challengeclient_id, code_challenge (PKCE)403: a challenge to showidentify, email_code, mfa, …one step per callthe address, the code, a second factor200: authorization_codeone use, 60 secondsPOST /tokencode, code_verifier, DPoP proofaccess, ID and refresh tokensbound to the page’s DPoP keyAuthorization: DPoP <access token>with a fresh proof for this requestverifies offline: signature,iss, aud, exp, permissions
The embedded login, which the SDKs drive. The hosted page is the same login behind a redirect: /authorize shows it and sends the browser back with the code.
  1. Your page starts an attempt with a PKCE challenge. SeekAuth answers 403 insufficient_authorization with a challenge to render (identify first) and an auth_session value that names the attempt.
  2. The page sends one step per call: the email address, the code from the email, a password, a passkey, a wallet signature, a second factor, accepting the terms. Each answer is the next challenge, or a refusal with a rejection code and the same challenge again.
  3. When nothing more is needed, SeekAuth answers 200 with an authorization code: one use, 60 seconds.
  4. The page exchanges it at /token with the PKCE verifier and a DPoP proof, and gets an access token, an ID token and (with offline_access) a refresh token, all bound to the page’s DPoP key.
  5. The page calls your API with the access token and a fresh proof. Your API verifies the token with the environment’s published keys, without asking SeekAuth.

An attempt lasts 15 minutes however far it got. The auth-react modal does all of this; auth-js exposes it step by step for a UI of your own.

Your app sends the browser to /authorize with the usual OpenID Connect parameters (response_type=code, client_id, redirect_uri, scope, state, nonce, and a PKCE code_challenge with code_challenge_method=S256). SeekAuth shows the login there, runs the same steps, and redirects back to your registered redirect_uri with code, state and iss. Your app exchanges the code at /token as above.

If the browser already has a session on the issuer host that is good enough for the request, /authorize answers at once, without a page. prompt=login always asks; prompt=none never shows a page and answers login_required instead; max_age and acr_values=aal2 ask for a recent or a two-step login. See /authorize.

After each step, SeekAuth works out what is still missing, in this order:

  1. A first factor: an email code, a password, a passkey, a provider or a wallet, from the methods the environment has enabled.
  2. The account’s standing: a disabled account is refused.
  3. A second factor, when the user has one, the environment requires two-step login, or the request asked for aal2. A user without one, where it is required, sets up an authenticator app first. See Two-step login.
  4. The app’s access: an app that is invite-only or closed lets in only the users it was granted. See Sign-ups and access.
  5. An email address, when the app needs one and the user has none (after a wallet or a provider that gave none).
  6. The app’s terms, once per user, when the app has a terms address.

A sign-up is the same attempt: an email code to an address nobody has makes the account, when sign-up is open. Answers are the same for addresses that have an account and addresses that do not, so the login cannot be used to find out who has one.

  • An access token for one API, with sub, sid, acr (aal1 or aal2), amr (how the user logged in), roles and permissions. Without a resource, it is for the client’s default API, or the account API when the client has none.
  • An ID token with the user’s profile for the scopes granted: name and picture with profile, email and email_verified with email.
  • A refresh token, with offline_access. It rotates on each use and ends the session if it is ever used twice.

See Tokens and claims.