# invalid_scope

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](https://www.nauthera.io/docs/v1/runbooks/oauth) · Generated from [`internal/runbook/oauth.yaml`](https://github.com/nauthera/nauthera-server/blob/main/internal/runbook/oauth.yaml) in nauthera-server.