/authorize
The start of the authorization code flow with PKCE, and the way into the hosted login page. The browser is sent here; when the user is signed in (or once they have logged in on the hosted page) it is sent back to the client’s redirect URI with an authorization code, which the client exchanges at /token.
Only the authorization code flow exists: response_type must be code. The implicit and hybrid flows, request objects (JAR) and pushed authorization requests (PAR) are not supported.
Parameters
Section titled “Parameters”| Parameter | Required | Meaning |
|---|---|---|
client_id |
yes | The client, a client of this environment. |
redirect_uri |
yes | Where the code goes. See the redirect URI. |
response_type |
yes | code, and nothing else. |
code_challenge |
yes | The PKCE challenge: the base64url SHA-256 of the code verifier, exactly 43 characters. |
code_challenge_method |
yes | S256. plain is refused. |
scope |
no | Space-separated. Only openid, profile, email, phone and offline_access are kept, in that order and once each; anything else is dropped. With none left the scope is openid. See scopes. |
state |
no | Returned unchanged with the code or the error. |
nonce |
no | Put into the ID token issued for this code. |
prompt |
no | login or none; see prompt. Other values are ignored. |
max_age |
no | Seconds. A session whose login is older than this is asked to log in again; 0 always asks. |
acr_values |
no | aal2 in the list asks for a second factor. |
resource |
no | The API the tokens are for (RFC 8707). See resource and audience. |
login_hint |
no | An address to fill the hosted page’s email field with. |
provider |
no | A social or custom provider (google, github, custom-acme, …) to send the browser straight to, without showing the page. |
session_ticket |
no | A session ticket that carries a login from another app of the group. Ignored with prompt=login. |
request and request_uri are refused with request_not_supported. Parameters not listed above, such as ui_locales, response_mode or claims, are ignored.
The client’s kind must be web, spa or native: a machine client uses the client credentials grant instead and is refused here with unauthorized_client.
The redirect URI
Section titled “The redirect URI”redirect_uri must be, character for character, one of the client’s registered redirect URIs. A query string on it is kept, and the code is added to it.
A development environment also accepts, without registering them, any http://localhost:<port>, http://127.0.0.1:<port> or http://[::1]:<port> address (without user info), so that local development needs no setup. A name under localhost, such as http://shop.your-app.localhost:5173, is accepted only when it is registered. Production takes only registered addresses.
The answer
Section titled “The answer”Success
Section titled “Success”Once the user is signed in, the browser is sent 303 See Other to the redirect URI:
HTTP/1.1 303 See OtherLocation: https://app.your-app.com/callback?code=Xv3n…&state=st4te&iss=https%3A%2F%2Fyour-app.auth.dev.seek.services| Parameter | Meaning |
|---|---|
code |
The authorization code: 43 characters, good for 60 seconds and one exchange. It is bound to the client, the redirect URI, the PKCE challenge, the nonce, the scope and the audience. |
state |
The request’s state, when it had one. |
iss |
The issuer (RFC 9207). Check it equals the issuer you sent the user to. |
When the user is not signed in, the answer is the hosted login page itself (200, HTML). The login attempt is kept in a cookie for 15 minutes.
Errors
Section titled “Errors”Errors come back two ways, depending on whether the client and its redirect URI have been verified yet:
- Before: an unknown
client_id, or aredirect_urithat is not the client’s, is shown as an HTML page with status400(“Unknown application”, “Redirect address not allowed”). The browser is never sent to an address that was not registered. - After: every other error is a
303 See Otherto the redirect URI witherror,error_description,state(when the request had one) andiss.
HTTP/1.1 303 See OtherLocation: https://app.your-app.com/callback?error=unsupported_response_type&error_description=response_type+must+be+code&state=st4te&iss=https%3A%2F%2Fyour-app.auth.dev.seek.serviceserror |
When |
|---|---|
unsupported_response_type |
response_type is not code. |
invalid_request |
code_challenge missing or not 43 characters, code_challenge_method not S256, max_age not a number of seconds, prompt=none combined with another value, or a session ticket that is invalid or expired. |
request_not_supported |
A request or request_uri parameter. |
unauthorized_client |
The client is a machine client. |
invalid_target |
resource names an API this client may not ask for. |
access_denied |
The app does not let this user in: its access mode, or the user’s standing in it. |
login_required |
prompt=none and nobody is signed in on this host. |
interaction_required |
prompt=none, and the request cannot be answered without showing something: a fresher or stronger login, terms to accept, an address to add, or a question to confirm (a native client’s, or a session ticket’s). |
server_error |
Something failed on the server. |
Single sign-on
Section titled “Single sign-on”The hosted page sets a session cookie on the issuer host. When the browser comes back with it, /authorize answers with a code at once, without showing anything, as long as:
- the login is fresh enough: no
max_age, or the user logged in withinmax_ageseconds; - it is strong enough: it passed a second factor, or nothing asks for one (neither
acr_values=aal2nor an environment that requires two-step login) and the user has no second factor; - the app lets the user in;
- nothing is still due: terms of the app to accept, or an email address the app needs.
Otherwise the hosted page is shown and asks only for what is missing: a session too old for max_age starts again from the known user’s credentials, and a session without a second factor is asked for one.
prompt
Section titled “prompt”prompt |
Behaviour |
|---|---|
| absent | Single sign-on when it can, the hosted page when it cannot. |
login |
Always shows the page. The session in the cookie ends when the new login completes. |
none |
Never shows anything: a code, or login_required / interaction_required. |
acr_values and max_age
Section titled “acr_values and max_age”acr_values=aal2 asks for a login with a second factor; the issued tokens then carry acr: "aal2". max_age=N asks for a login in the last N seconds, and max_age=0 for one now. Both are how an app asks for a step-up before a sensitive action.
Native clients: “Continue to …?”
Section titled “Native clients: “Continue to …?””A native client whose redirect URI another app on the device could also register (a private-use scheme such as com.your-app:/callback, or a loopback address) is not answered silently from the session cookie (RFC 8252, section 8.6). The page asks “Continue to {app}?” with “Continue as {email}” and “Use another account” instead, and the code is issued only once the user has said yes, in the same browser. With prompt=none that question is interaction_required. A native client that redirects to an https address is answered as any other.
Session tickets
Section titled “Session tickets”With session_ticket, the browser arrives signed in as the user who minted the ticket in another app of the same group, after the page asks “Continue to {app}?” (or “Switch account?” when someone else is signed in). See Session tickets.
Example
Section titled “Example”GET /authorize?response_type=code &client_id=your-app-web &redirect_uri=https%3A%2F%2Fapp.your-app.com%2Fcallback &scope=openid+email+offline_access &state=st4te &nonce=n0nce &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 HTTP/1.1Host: your-app.auth.dev.seek.servicesWith nobody signed in this answers the hosted page; after the login, the browser goes to https://app.your-app.com/callback?code=…&state=st4te&iss=https%3A%2F%2Fyour-app.auth.dev.seek.services. With a session cookie that satisfies the request, the 303 comes at once.
The SDKs build this request for you: loginWithRedirect() in auth-js and auth-react, and the web client of the Rust SDK.