# `Attesto.Plug.RequireScopes`
[🔗](https://github.com/XukuLLC/attesto/blob/v0.13.0/lib/attesto/plug/require_scopes.ex#L2)

Authorize a request against the scopes on the verified token.

Runs after `Attesto.Plug.Authenticate` (which assigns the verified
claims): it reads the `scope` claim, splits it, and checks that the
granted set covers every required scope via `Attesto.Scope`. On
success the conn passes through; otherwise it answers 403
`insufficient_scope` (RFC 6750 §3.1).

    plug Attesto.Plug.RequireScopes, ["documents.read"]

Options. The first argument may be a bare list of required scopes, or a
keyword list with:

  * `:scopes` (required) - the list of required concrete scopes.
  * `:claims_key` - the `conn.assigns` key the claims were put under
    (default `:attesto_claims`, matching `Attesto.Plug.Authenticate`).
  * `:resource_metadata` - the URL of this resource's protected-resource
    metadata (RFC 9728), advertised as a `resource_metadata` auth-param on
    the 403 `insufficient_scope` (and the 401 `invalid_token` for an
    unauthenticated request) `WWW-Authenticate` challenge (RFC 9728 §5.1).
  * `:send_error`, `:www_authenticate`, `:no_store` - the transport hooks
    `Attesto.Plug.OAuthError` honors, threaded onto BOTH the 403 and the 401
    this plug renders so a host can override the response envelope and inject
    a per-conn challenge (e.g. a request-derived `resource_metadata` pointer)
    on the scope-rejection path, not just the authentication-rejection path.

A request that reaches this plug without verified claims (the
authentication plug did not run or did not assign them) is treated as
unauthenticated and answered 401.

Part of the optional `Attesto.Plug` layer; compiles only with `Plug`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*