OAuth2 / OIDC authorization endpoint (POST form)

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program

POST/authorize

The POST form of the authorization endpoint. OIDC Core §3.1.2.1: "The Authorization Server MUST support the use of the HTTP GET and POST methods defined in RFC 7231 at the Authorization Endpoint." RFC 6749 §3.1 says the same.

It behaves IDENTICALLY to GET — the same validation, the same errors, the same redirect — because the method is a transport choice, not a different authorization. Parameters arrive application/x-www-form-urlencoded instead of in the query string, which keeps a long or sensitive request (a JAR request object, rich authorization details) out of the URL, browser history, Referer headers and proxy logs.

NO cross-site check applies here, unlike the interactive endpoints. An authorization request is cross-origin BY DESIGN: it is how a relying party hands the user to this server, and it is typically a form auto-submitted from the client's own origin. Rejecting it on Origin or Sec-Fetch-Site would break the flow the endpoint exists for. Its safety comes from the same places the GET form's does — the exactly-matched redirect_uri, PKCE, and the fact that no state changes until the user acts.

POST/authorize

curl -i -X POST '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'

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.

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.

Request body

application/x-www-form-urlencoded

Authorization-request parameters pushed to the PAR endpoint (RFC 9126). Mirrors the /authorize query parameters plus client authentication.

request_uristring
MUST NOT be sent; present only so the server can reject it.
at most 512 characters
response_typestring
Example"code"
at most 64 characters
max_ageinteger · int64
at least 0
client_idstring
Example"nauthera_2Rk9"
1–256 characters · pattern ^[!-~]+$
redirect_uristring · uri
Example"https://app.example.com/callback"
at most 2048 characters
scopestring
Example"openid profile email"
at most 2048 characters · pattern ^\S+( \S+)*$
statestring
at most 1024 characters
noncestring
at most 1024 characters
response_modestring
at most 64 characters
promptstring
at most 64 characters · pattern ^(none|login|consent|select_account)( (none|login|consent|select_account))*$
login_hintstring
at most 512 characters
ui_localesstring
at most 256 characters · pattern ^\S+( \S+)*$
acr_valuesstring
at most 512 characters · pattern ^\S+( \S+)*$
claimsstring
at most 8192 characters
code_challengestring
43–128 characters · pattern ^[A-Za-z0-9_-]+$
code_challenge_methodstring
at most 64 characters
requeststring
at most 16384 characters
authorization_detailsstring
at most 8192 characters
resourcestring · uri
at most 2048 characters
dpop_jktstring
exactly 43 characters · pattern ^[A-Za-z0-9_-]+$
client_secretstring
at most 512 characters
client_assertion_typestring
Example"urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
at most 128 characters
client_assertionstring
at most 16384 characters

Responses

302 FoundRedirect to the client redirect_uri (or to the hosted login/consent UI). Carries the same session_state and Set-Cookie as the GET form — the two share one handler, and a security-relevant header on only one of them would be a difference nothing in the specification asks for.
Redirect to the client redirect_uri (or to the hosted login/consent UI). Carries the same session_state and Set-Cookie as the GET form — the two share one handler, and a security-relevant header on only one of them would be a difference nothing in the specification asks for.
Headers
- Locationstring
- Cache-Controlno-store
- 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 last path segment of type), so consumers can branch on it without parsing prose. type is https://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code has about:blank. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"https://nauthera.io/problems/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 values43 values
  invalid_request
  invalid_credentials
  forbidden
  unauthorized
  insufficient_user_authentication
  protected_account
  password_held_by_directory
  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
  password_reused
  password_too_short
  password_too_long
  password_compromised
  invalid_verification_link
  invalid_invitation_link
  mail_relay_missing
  email_unverified
  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
  The error code's runbook (RFC 6749 §5.2): https://nauthera.io/runbooks/oauth/<error>.
  Example"https://nauthera.io/runbooks/oauth/invalid_request"
- statestring
  Echoed authorization-request state (RFC 6749 §4.1.2.1).
- issstring · uri
  Issuer identifier on authorization error responses (RFC 9207).

PreviousOAuth2 / OIDC authorization endpoint NextPushed Authorization Request

Authorization

Headers

Request body

Responses

Headers

Body

Headers

Body