OAuth2 / OIDC authorization endpoint

GET/authorize

Starts the authorization-code flow (RFC 6749 §4.1, OIDC Core). PKCE is required for public clients and enforced for all per RFC 9700; the code_challenge is bound to the code and verified at the token endpoint.

On success redirects (302) to the client's exactly-registered redirect_uri with code, state, and iss (RFC 9207). On error the server returns a direct error and never redirects to an unvalidated URI.

Supports pushed authorization requests via request_uri (RFC 9126), request objects via request / request_uri (RFC 9101 JAR), rich authorization via authorization_details (RFC 9396), resource indicators (RFC 8707), and DPoP key binding via dpop_jkt (RFC 9449).

GET/authorize

curl -G -i 'https://auth.example.com/authorize' \
  --data-urlencode 'response_type=code' \
  --data-urlencode 'client_id=nauthera_2Rk9' \
  --data-urlencode 'redirect_uri=https://app.example.com/callback' \
  --data-urlencode 'scope=openid profile email' \
  --data-urlencode 'state=af0ifjsldkj' \
  --data-urlencode 'nonce=n-0S6_WzA2Mj' \
  --data-urlencode 'response_mode=query' \
  --data-urlencode 'prompt=consent' \
  --data-urlencode 'max_age=3600' \
  --data-urlencode 'ui_locales=en-US fr-CA' \
  --data-urlencode 'code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' \
  --data-urlencode 'code_challenge_method=S256'

Response

302 Found

No body: the client follows the Location header.

Authorization

None. This endpoint does not take API credentials.

It reads the browser session from the Cookie header.

The request Cookie header; the interactive login / pending-auth session cookie, and the browser marker a sign-in is recognized by, are read from it.

Query parameters

response_typeenum
The grant/response type. code for the authorization-code flow. Required unless the request arrives by request_uri (RFC 9126), in which case it comes from the pushed request.
Possible values"code"
client_idstringrequired
The registered client identifier (printable ASCII, no spaces).
Example"nauthera_2Rk9"
1–256 characters · pattern ^[!-~]+$
redirect_uristring · uri
Must exactly match a registered redirect URI (RFC 9700 §2.1).
Example"https://app.example.com/callback"
at most 2048 characters
scopestring
Space-delimited scopes. openid requests an ID token.
Example"openid profile email"
at most 2048 characters · pattern ^\S+( \S+)*$
statestring
Opaque CSRF value echoed back on the response.
Example"af0ifjsldkj"
at most 1024 characters
noncestring
OIDC value bound into the ID token to mitigate replay.
Example"n-0S6_WzA2Mj"
at most 1024 characters
response_modeenum
How the authorization response is returned to the client.
Possible values"query""fragment""form_post"
promptstring
Space-delimited OIDC prompt values (none, login, consent, select_account).
Example"consent"
at most 64 characters · pattern ^(none|login|consent|select_account)( (none|login|consent|select_account))*$
displayenum
Possible values"page""popup""touch""wap"
max_ageinteger
Maximum authentication age in seconds (OIDC).
Example3600
between 0 and 315360000
login_hintstring
at most 512 characters
id_token_hintstring
A previously issued ID token hinting the current session.
at most 8192 characters
ui_localesstring
Space-delimited BCP47 language tags for the UI.
Example"en-US fr-CA"
at most 256 characters · pattern ^\S+( \S+)*$
acr_valuesstring
Space-delimited requested Authentication Context Class References.
at most 512 characters · pattern ^\S+( \S+)*$
claimsstring
OIDC claims request (a JSON object, URL-encoded).
at most 8192 characters
code_challengestring
PKCE challenge (RFC 7636). base64url, required for public clients.
Example"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
43–128 characters · pattern ^[A-Za-z0-9_-]+$
code_challenge_methodenum
Possible values"S256"
requeststring
A JWT-Secured Authorization Request object (RFC 9101 JAR).
at most 16384 characters
request_uristring
Reference to a pushed (RFC 9126) or hosted (RFC 9101) request object, e.g. urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14.
at most 2048 characters · pattern ^(urn:ietf:params:oauth:request_uri:|https://)\S+$
authorization_detailsstring
Rich Authorization Requests (RFC 9396), a JSON array (URL-encoded).
at most 8192 characters
resourcestring · uri
Resource indicator (RFC 8707) identifying the target resource server.
at most 2048 characters
dpop_jktstring
JWK SHA-256 thumbprint (base64url, 43 chars) binding the code to a DPoP key (RFC 9449).
exactly 43 characters · pattern ^[A-Za-z0-9_-]+$

Headers

Cookiestring
The request Cookie header; the interactive login / pending-auth session cookie, and the browser marker a sign-in is recognized by, are read from it.

Responses

302 FoundRedirect back to the client with an authorization code, OR to the hosted login UI (/login) when no valid session exists. The Location carries code, state (if supplied) and iss (RFC 9207) on the success path, or the preserved authorization parameters on the login path.
Redirect back to the client with an authorization code, OR to the hosted login UI (/login) when no valid session exists. The Location carries code, state (if supplied) and iss (RFC 9207) on the success path, or the preserved authorization parameters on the login path.

When the deployment serves OIDC Session Management 1.0 the success Location additionally carries session_state (§3), the value the relying party's iframe polls check_session_iframe with. It is absent otherwise, and absent for a client whose redirect URI has no web origin (a native custom scheme), which has nothing to compare against.
Headers
- Locationstring
- Cache-Controlno-store
- Pragmano-cache
- Set-Cookiearray of strings
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/jsonOAuth2 error response (RFC 6749 §5.2).
OAuth2 error response (RFC 6749 §5.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
An OAuth2 error response (RFC 6749 §5.2). iss (RFC 9207) is present on authorization-endpoint error responses so clients can detect mix-up.
- errorstringrequired
  A single ASCII error code.
  Example"invalid_request"
- error_descriptionstring
  Example"client_id, redirect_uri and response_type are required"
- error_uristring · uri
- statestring
  Echoed authorization-request state (RFC 6749 §4.1.2.1).
- issstring · uri
  Issuer identifier on authorization error responses (RFC 9207).

PreviousOAuth2 NextOAuth2 / OIDC authorization endpoint (POST form)

OAuth2 / OIDC authorization endpoint

GET/authorize

Headers

Body

Headers

Body

Headers

Body

Headers

Body