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_scope

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

The requested scope is not registered for the client, or asks for more than the grant holds (RFC 6749 §4.1.2.1, §5.2).

Meaning

Sent when a requested scope is not among the client's registered scopes: at /authorize (redirected to the client), /par, /device_authorization, and at /token for client_credentials. On a refresh, a scope wider than the scope originally granted is refused too; a refresh may only narrow.

Impact

The request fails until the client asks for scopes it is registered for. It is a mismatch between the application and its registration, often after a new scope was added in code but not to the registration.

Diagnosis

  1. The audit record has reason invalid_scope and cause scope_not_registered or scope_exceeds_grant, and records the scope that was asked for. Find it by X-Request-ID on the Troubleshooting page.
  2. Compare with the client's registered scopes (dashboard client page, or spec.scopes on its OIDCClient).

Mitigation

  • As a client developer: request only registered scopes; on refresh, request the original scope or less, or omit scope.
  • As an operator: add the scope to the client's registration if it should have it. Dynamically registered clients are limited to openid, profile and email.
  • As a user: tell the application's owner.

Escalation

If a registered scope is refused, open an issue with the request id, the server version, the scope requested and the scopes registered. Never attach tokens.

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