Skip to content

/authorize

GET/authorizeissuer host

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.

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.

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.

Once the user is signed in, the browser is sent 303 See Other to the redirect URI:

HTTP/1.1 303 See Other
Location: 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 come back two ways, depending on whether the client and its redirect URI have been verified yet:

  • Before: an unknown client_id, or a redirect_uri that is not the client’s, is shown as an HTML page with status 400 (“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 Other to the redirect URI with error, error_description, state (when the request had one) and iss.
HTTP/1.1 303 See Other
Location: 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.services
error 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.

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 within max_age seconds;
  • it is strong enough: it passed a second factor, or nothing asks for one (neither acr_values=aal2 nor 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 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=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.

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.

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.

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.1
Host: your-app.auth.dev.seek.services

With 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.