Skip to content

Embedded login (/authorize-challenge)

The embedded login is a login that runs on your own page: your page sends the user’s answers one step at a time, and SeekAuth replies with what to show next, until it hands over an authorization code. auth-react’s modal and auth-js’s beginLogin() drive this endpoint for you; this page is for a login UI of your own. The hosted page applies exactly the same steps through /hosted/challenge. See How login works.

POST/authorize-challengeissuer host
  • Body: one flat JSON object: the envelope below and, when the call carries a step, the step’s members beside it.
  • Clients: first-party clients of kind web, spa or native (the clients you register are first-party). Others get unauthorized_client.
  • Origin: when the browser sends an Origin, it must be one of the client’s allowed origins, or unauthorized_client “this origin is not allowed for the client”. A development environment also accepts any localhost origin; production accepts only the registered ones. Preflight requests allow the DPoP header.
  • Unknown members are ignored. A body that is not JSON is invalid_request.
Field Required Meaning
client_id Yes The client.
code_challenge Yes PKCE: 43 base64url characters, the SHA-256 of your code verifier.
code_challenge_method Yes S256.
scope No Space-separated. Only openid, profile, email, phone and offline_access are kept; none left means openid.
nonce No Put into the ID token.
resource No The API the tokens are for, which the client must be allowed to name; otherwise invalid_target. Without it, the client’s default API, or the account API.
acr_values No aal2 asks for a second factor. See step-up.
max_age No Seconds. A session older than that proves a factor again; 0 always asks.
device_id No 1 to 64 printable characters that stay the same on a device. A device the account has used gets code emails of its own under the rate limits.
turnstile_token No A solved captcha.

There is no redirect_uri: the code goes back in the answer. The first call may carry a step already (such as identify), or none, in which case the answer is the first challenge to show.

Every later call sends client_id, the auth_session from the last answer, the step’s members, and turnstile_token when a captcha was solved.

{ "client_id": "your-app-spa", "auth_session": "Q2x...", "step": "email_code", "code": "123456" }

To raise the session the user already has, rather than start a new one, send the first call with the current access token and a DPoP proof for it, and no auth_session:

POST /authorize-challenge
Authorization: DPoP eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2In0...
Content-Type: application/json
{ "client_id": "your-app-spa", "code_challenge": "...", "code_challenge_method": "S256", "acr_values": "aal2", "max_age": 0 }

The token must have been issued to this client (invalid_token “the access token was issued to another client”) and its session must still be good (invalid_token “the session has ended”). A missing or wrong proof is invalid_dpop_proof. The login then asks only for what is missing, and the code it ends with raises the same session.

auth_session is a secret that names the attempt. Keep it in memory for the attempt and send it back as it is.

  • An attempt lasts 15 minutes from its start, however far it got.
  • It is bound to the client and to the Origin that started it.
  • An unknown or expired auth_session, one of another client or origin, or one of an attempt that already completed, gets 400 invalid_session “this login attempt expired, start over”. Start again with a first call.

Status 403, with the challenge to show:

{
"error": "insufficient_authorization",
"error_description": "more is needed to log in",
"auth_session": "Q2x...",
"challenge": { "type": "email_code", "sent_to": "a***@example.com", "expires_in": 600, "purpose": "login" },
"rejected": { "code": "invalid_code", "message": "That code is not right.", "attempts_left": 3 }
}

rejected is there when the last step was refused; the attempt goes on, and challenge says what to show now. attempts_left comes only with a wrong email code.

Status 200:

{ "authorization_code": "kL8v..." }

The code works once, for 60 seconds, for this client and the PKCE challenge of the first call. Exchange it at /token with grant_type=authorization_code, the code_verifier and no redirect_uri. Both answers carry Cache-Control: no-store.

Each call carries at most one step, named by step:

step Members What it does
identify email Names the user’s address.
email_code code? Without code, sends a code (again). With it, checks the code.
password email?, password Logs in with a password.
signup email, password?, display_name?, terms_accepted? Makes an account with the sign-up form.
password_reset email? or new_password? With email, starts a reset. With new_password, sets it once the reset code was right.
totp code An authenticator-app code, or the first one when setting one up.
recovery_code code A recovery code.
wallet_challenge chain (solana or evm), address, chain_id? Asks for the message a wallet signs. See Wallets.
wallet_verify address, signed_message, signature Sends the wallet’s signature. For EVM, signed_message is left out.
passkey_challenge Asks for passkey request options. The attempt’s state does not change, so a browser prompt can wait in the email field’s autofill.
passkey_verify credential The output of PublicKeyCredential.toJSON().
accept_terms Accepts the app’s terms.
add_email email Gives an account without an address one. A code goes to it.
continue Goes on after the recovery_codes challenge, once the user has kept the codes.

There is no step for social or custom providers: send the browser to /authorize with provider=<id>, which goes straight to the provider.

challenge.type says what to show. A login UI must have a fallback, such as sending the user to the hosted page, for a type it does not know.

type Members When
identify methods (the environment’s login methods), signup (whether sign-up is offered) Nothing chosen yet.
credentials email, methods (which of password and email_code are on) An address was named.
email_code sent_to (masked, such as a***@example.com), expires_in (seconds), purpose (login, signup, verify, reset or attach) A code is out.
new_password min_length, max_length The reset code was right.
mfa methods: the user’s own second factors, in the order passkey, totp, recovery_code A second factor is due.
totp_enroll secret (base32), otpauth_uri Two-step login is required and the user has no second factor yet.
recovery_codes codes Right after a second factor was set up. The codes are filled once and empty if asked again.
wallet chain, input (what the wallet signs) A wallet was asked to sign.
passkey options (for navigator.credentials.get()) The answer to passkey_challenge.
terms terms_url, app The app’s terms are due.
add_email app The app needs an address and the user has none.

Examples the server sends:

{ "type": "credentials", "email": "[email protected]", "methods": ["password", "email_code"] }
{ "type": "new_password", "min_length": 15, "max_length": 64 }
{ "type": "mfa", "methods": ["totp", "recovery_code"] }
{ "type": "add_email", "app": "Your App" }

A refused step answers 403 with rejected: { code, message } beside the challenge. The message is written for the user and can be shown as it is.

code Message
captcha_required Confirm you are not a robot.
unexpected_step That step does not fit where this login is.
invalid_email Enter a valid email address. Or the environment’s message for a tagged or throwaway address (see Bot protection).
method_disabled Email login is not enabled. / Email codes are not enabled. / Password login is not enabled. / Passkeys are not enabled. / This wallet login is not enabled.
invalid_credentials Wrong email or password.
signup_closed Signing up is not open for this app.
terms_required Accept the terms to create an account.
password_too_short Use at least {min} characters.
password_too_long Use at most 64 characters.
password_breached This password appeared in a data breach. Choose another one.
invalid_code For an email code: That code didn’t work. Request a new one, or sign in another way. (Also the answer to any code once the address’s answers for the day are spent; see Rate limits.) For a second factor: That code is not right. Enter the current code from your authenticator app. / That recovery code is not right.
codes_paused That code was right, but email codes for this address are paused for up to a day after too many wrong tries. Sign in another way, such as with a password, a passkey or a linked account, or ask for a code later. (The right email code once the address’s checked answers for the day are spent: the code ends and the login goes back to choosing a way in. Only somebody holding the right code sees it.)
second_factor_paused That code was right, but two-step codes for this account are paused for up to a day after too many wrong tries. Sign in on a device you have used before, or with a passkey, or try again later. (The right authenticator-app or recovery code once the account’s checked answers for the day are spent; see Rate limits. Only somebody holding the right code sees it.)
code_expired That code expired. Request a new one.
account_exists This email already has an account. Log in instead.
email_unavailable That address cannot be used. Enter another one.
invalid_passkey That passkey did not work here. Try again, or log in another way.
invalid_address That is not a wallet address.
invalid_signature The wallet’s signature could not be verified.
account_disabled This account is disabled.
access_denied This account does not have access to {app}. The attempt starts over.
session_ended Your session has ended. Please log in again. / This login can no longer be finished, because the account changed meanwhile. Start again. (The account the login stood for changed under it: another address, a second step it did not have. The attempt starts over.)

On captcha_required, show the captcha (its site key is captcha_site_key in /ui/config) and send the same step again with turnstile_token.

Errors that end the call rather than refuse a step are OAuth errors, { "error", "error_description" }:

error Status When
invalid_request 400 The body is not JSON or is malformed, a step is unknown or malformed, client_id or code_challenge is missing, code_challenge_method is not S256.
unauthorized_client 400 The client may not use this endpoint, or the origin is not allowed.
invalid_session 400 The attempt is unknown, expired, of another client or origin, or done.
invalid_target 400 resource names an API the client may not ask for.
invalid_dpop_proof 400 A step-up without a valid DPoP proof.
invalid_token 401 A step-up with a token of another client or an ended session.
temporarily_unavailable 429 A rate limit; Retry-After says when to try again.
server_error 500
POST/hosted/challengehosted page only

The hosted page served at /authorize runs the same steps on this endpoint. It is for that page only: the Origin must be the issuer itself. Instead of client_id and auth_session, its body carries flow, which names the attempt’s cookie (__Host-as-…, HttpOnly, 15 minutes), set when /authorize started the attempt. A challenge answers 403 as above, without auth_session. Done, it answers 200 { "redirect_to": "…" }: the client’s redirect_uri with code, state and iss, or with error=access_denied when the app refuses the user; it also sets the browser’s session cookie, so the next login is answered from it.

GET/ui/config?client_id=…issuer host

What a login UI shows for a client. Cached for a minute (Cache-Control: public, max-age=60). An unknown client is 404 not_found.

Field Meaning
issuer The environment’s issuer.
app { name } of the client’s app.
client { name, type }.
theme The app’s theme, or the environment’s. See Branding.
methods The environment’s login methods.
providers [{ id, label }] of the custom providers that are on.
signup Whether sign-up is offered: open in the environment and the app is open to everyone.
terms_url The app’s terms, or null.
captcha_site_key The Turnstile site key, or null when the platform has no captcha.
passkey_rp_id The passkey domain, or null.
POST /authorize-challenge
Origin: http://localhost:5173
Content-Type: application/json
{ "client_id": "your-app-dev-spa", "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
"code_challenge_method": "S256", "scope": "openid profile email offline_access", "device_id": "device-7f3a" }
403
{ "error": "insufficient_authorization", "error_description": "more is needed to log in",
"auth_session": "Q2x...",
"challenge": { "type": "identify", "methods": ["email_code"], "signup": true } }
POST { "client_id": "your-app-dev-spa", "auth_session": "Q2x...", "step": "identify", "email": " [email protected] " }
403 { ..., "challenge": { "type": "email_code", "sent_to": "a***@example.com", "expires_in": 600, "purpose": "login" } }
POST { "client_id": "your-app-dev-spa", "auth_session": "Q2x...", "step": "email_code", "code": "123456" }
200 { "authorization_code": "kL8v..." }

The same auth_session sent again now gets invalid_session. The code goes to /token with the code verifier and a DPoP proof.