Skip to content

require_scopes

require_scopes(*scopes, require_all=True) — builds a guard that requires AuthUser.scopes to cover the given OAuth scopes.

Signature

def require_scopes(*scopes: str, require_all: bool = True) -> type:
    ...

Semantics

OAuth scopes are AND by default: the user must possess every listed scope.

require_all Meaning
True (default) user has all of scopes (AND)
False user has at least one of scopes (OR)

Examples

@use_guards(require_scopes("items.read"))                    # must have items.read
@use_guards(require_scopes("items.read", "items.write"))     # both (default AND)
@use_guards(require_scopes("manage", "audit", require_all=False))  # either

Where scopes come from

Guards populate AuthUser.scopes from the credential:

  • jwt_bearer — the scope claim (space-separated string or list).
  • oauth2_introspection — the scope field of the introspection response.
  • session_cookie — session.data["scopes"] via the default user_builder.
  • bearer_token / api_key — whatever your verify returns.

Behaviour

  • No AuthUser on state → UnauthorizedError (401).
  • User present but scopes don't satisfy → ForbiddenError (403).