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.
The endpoint
Section titled “The endpoint”- 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,spaornative(the clients you register are first-party). Others getunauthorized_client. - Origin: when the browser sends an
Origin, it must be one of the client’s allowed origins, orunauthorized_client“this origin is not allowed for the client”. A development environment also accepts anylocalhostorigin; production accepts only the registered ones. Preflight requests allow theDPoPheader. - Unknown members are ignored. A body that is not JSON is
invalid_request.
The request
Section titled “The request”The first call
Section titled “The first call”| 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.
Later calls
Section titled “Later calls”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" }Step-up
Section titled “Step-up”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-challengeAuthorization: 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.
The login attempt
Section titled “The login attempt”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
Originthat started it. - An unknown or expired
auth_session, one of another client or origin, or one of an attempt that already completed, gets400 invalid_session“this login attempt expired, start over”. Start again with a first call.
The answers
Section titled “The answers”More is needed
Section titled “More is needed”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.
Challenges
Section titled “Challenges”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": "new_password", "min_length": 15, "max_length": 64 }{ "type": "mfa", "methods": ["totp", "recovery_code"] }{ "type": "add_email", "app": "Your App" }Rejections
Section titled “Rejections”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
Section titled “Errors”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 |
The hosted page
Section titled “The hosted page”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.
The login UI’s configuration
Section titled “The login UI’s configuration”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. |
An email-code login from start to end
Section titled “An email-code login from start to end”POST /authorize-challengeOrigin: http://localhost:5173Content-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.