Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

invalid_request

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

The request lacks a parameter, combines parameters wrongly or breaks a rule checked before any grant is evaluated (RFC 6749 §4.1.2.1, §5.2).

Meaning

Sent by /authorize, /par, /token and /device_authorization. In this server:

  • /token: no grant_type; no code, refresh_token or device_code for the grant; a code with a PKCE challenge redeemed without code_verifier; a malformed Basic header, more than one client authentication method, a body client_id that differs from the Basic one, or a client_assertion without its type or of an unsupported type.
  • /authorize, redirected to the client: a plain request from a client registered to require a signed request object, a response_mode other than query (other than fragment for an implicit request), no PKCE challenge where the client or organization requires one, or a method other than S256; a claims parameter that is not a JSON object of claim requests; and for an implicit request, no nonce, no openid scope, or a dpop_jkt. An implicit request's error is in the redirect's fragment.
  • /authorize, answered directly: an unknown client_id, a redirect_uri that is not registered (or missing while the client has several), a front-channel request where PAR is required, a request_uri that is unknown, spent or another client's, or a request object that does not verify. All of these answer only invalid_request and iss, so an unregistered client and a wrong redirect look the same.
  • /par: a request_uri in the push, a client_id other than the authenticated client, or any rule /authorize applies.

Impact

Nearly always an integration bug or a registration that does not match the app: the same request fails the same way every time. A redirected error reaches the app's callback, and what the user sees there is up to the app. A direct /authorize refusal never returns to the app: the user is left on the server, and a browser on the main organization sees an error page showing a Reference ID.

Diagnosis

  1. Read error_description; it names the rule everywhere except on a direct /authorize refusal.
  2. Paste the response's X-Request-ID (or the Reference ID the user saw) into the admin dashboard's Troubleshooting page. See Tracing a failed request.
  3. The audit action is oauth.authorization.requested (/authorize, /par), oauth.token.issued or oauth.token.refreshed (/token), oauth.device.requested, or oauth.client_authentication.attempted for a malformed client credential. A direct refusal is recorded under the rule as its reason (unregistered_client, redirect_uri_required, invalid_redirect_uri, pushed_request_required, invalid_request_uri, request_uri_client_mismatch, invalid_request_object); elsewhere the reason is invalid_request and the cause names the rule (parameter_missing, pkce_required, pkce_method_unsupported, response_mode_unsupported, dpop_jkt_without_code, claims_malformed, signed_request_required, multiple_auth_methods, …).
  4. Compare the request with the client's registration on the dashboard's client page or its OIDCClient resource: redirect URIs are matched exactly.

Mitigation

  • As a client developer: fix what the description or the recorded cause names. Send one client authentication method, the redirect_uri exactly as registered, and an S256 PKCE challenge.
  • As an operator: for a direct refusal of a registered app, compare its redirect_uri with the registration character by character (scheme, port, path, trailing slash). With fapi.require_pushed_authorization_requests on, every client must use /par.
  • As a user: go back to the application and start again; if it repeats, give the application's support the Reference ID.

Escalation

If the recorded rule is one the request did not break, or a request accepted before an upgrade is refused after it, open an issue with the request id, the server version (nauthera-server version), the endpoint and the reason and cause from the audit record. Never attach codes, tokens, secrets, request objects or client assertions.

OAuth error runbooks · Generated from internal/runbook/oauth.yaml in nauthera-server.