Enum TokenRejection 

#[non_exhaustive]
pub enum TokenRejection {
    Missing,
    Invalid(InvalidToken),
    InsufficientScope,
}

Why a bearer credential was refused, and — crucially — with which HTTP status.

The split is the whole point: RFC 6750 distinguishes “this token is not good” (401 invalid_token, go get a new one) from “this token is fine but not sufficient” (403 insufficient_scope). A client that gets 401 for an insufficient-scope token will loop through the authorization flow forever and land back on the same refusal.

Variant	Status	WWW-Authenticate (with OAuth configured)
Missing	401	crate::OAuthValidator::invalid_token_challenge
Invalid	401	crate::OAuthValidator::invalid_token_challenge
InsufficientScope	403	crate::OAuthValidator::insufficient_scope_challenge

#[non_exhaustive]: treat a variant this code does not know as a 401.

It implements std::error::Error, so ? carries it into Box<dyn Error> or anyhow. Display deliberately renders the category only — missing credential, invalid token, insufficient scope — and never Invalid’s reason, so a careless format!("{e}") in a response body cannot tell a caller which check failed. The reason is reachable through the variant itself (InvalidToken) and through Debug, for logs.

use oauth_resource_server::{InvalidToken, InvalidTokenKind, TokenRejection};

let e = TokenRejection::Invalid(InvalidToken::new(
    InvalidTokenKind::WrongAudience,
    "token rejected: InvalidAudience",
));
assert_eq!(e.to_string(), "invalid token");
assert!(format!("{e:?}").contains("InvalidAudience"));

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Missing

401: the request carried no credential at all. Separate from Invalid so a server can log it quietly — every OAuth client’s first request looks like this — not because the response differs (it should not: a missing credential gets the same invalid_token challenge as a bad one).

Invalid(InvalidToken)

401 invalid_token: malformed, unsigned, wrong issuer/audience/type, expired, or signed by a key we could not obtain. The InvalidToken says which check failed: its kind is stable and matchable (a metrics label via InvalidTokenKind::as_str), its detail is for logs only — never return it to the caller, since telling an unauthenticated client exactly which check failed is a free oracle.

InsufficientScope

403 insufficient_scope: signature, issuer, audience and expiry all passed, but the token does not carry every required scope.

Trait Implementations

impl Clone for TokenRejection

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TokenRejection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for TokenRejection

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for TokenRejection

impl Error for TokenRejection

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<MissingScopes> for TokenRejection

fn from(_: MissingScopes) -> Self

Converts to this type from the input type.

impl PartialEq for TokenRejection

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for TokenRejection