Skip to content

xtr_security_jwt.exception

The errors this library raises, one family under one base.

The signing and verification failures derive from :class:JwtFailureError (itself a :class:~xtr_security_core.exception.SecurityError); the errors the authenticator raises for a request derive from the family's :class:~xtr_security_core.exception.AuthenticationError. One except SecurityError still catches every one of them.

ExpiredTokenError

ExpiredTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)

Bases: AuthenticationError

A caller presented a token whose expiry has passed.

Drawn from the family's :class:~xtr_security_core.exception.AuthenticationError so the firewall turns it into a challenge; its public message names the expiry rather than leaking why the token was refused.

InvalidPayloadError

InvalidPayloadError(invalid_key: str, message: str | None = None)

Bases: AuthenticationError

A verified token carried no claim naming the user it stands for.

The signature checked, but the claim the manager reads the user's identifier from — the configured user-id claim — was absent, so the token proves nobody. Drawn from :class:~xtr_security_core.exception.AuthenticationError.

Attributes:

  • invalid_key (str) –

    The claim the payload was expected to carry.

Record the invalid_key the payload did not carry.

InvalidTokenError

InvalidTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)

Bases: AuthenticationError

A caller presented a token that is malformed, unsigned or tampered with.

The catch-all for a token the verifier refused for any reason other than expiry: a bad signature, a disallowed algorithm, a structural fault. Drawn from :class:~xtr_security_core.exception.AuthenticationError.

JwtDecodeFailureError

JwtDecodeFailureError(reason: str, message: str, *, payload: Mapping[str, object] | None = None)

Bases: JwtFailureError

Reading a token back into claims failed.

Its reason tells the three apart: :data:INVALID_TOKEN for a token that could not be read or whose issued-at time is in the future, :data:EXPIRED_TOKEN for one past its expiry, and :data:UNVERIFIED_TOKEN for one whose signature does not verify against any known key.

JwtEncodeFailureError

JwtEncodeFailureError(reason: str, message: str, *, payload: Mapping[str, object] | None = None)

Bases: JwtFailureError

Signing a set of claims into a token failed.

Its reason is :data:INVALID_CONFIG when the signing key or algorithm the provider was built with cannot produce a signature, or :data:UNSIGNED_TOKEN when the provider returned a token it did not sign.

JwtFailureError

JwtFailureError(reason: str, message: str, *, payload: Mapping[str, object] | None = None)

Bases: SecurityError

A token could not be signed or verified, carrying a machine reason.

The base of the encode and decode failures. It carries a reason — one of the reason constants its subclasses declare — and, when a token was read far enough to have one, the payload that was decoded. Deriving from the family's :class:~xtr_security_core.exception.SecurityError keeps one except SecurityError catching every error the family raises.

Attributes:

  • reason (str) –

    The machine-readable cause, a subclass reason constant.

  • payload (dict[str, object] | None) –

    The claims decoded before the failure, when there were any.

Record the reason and the payload decoded before failing.

get_reason

get_reason() -> str

Return the machine-readable cause of the failure.

get_payload

get_payload() -> Mapping[str, object] | None

Return the claims decoded before the failure, or None.

MissingKeyError

MissingKeyError(location: str | None = None)

Bases: InvalidArgumentError

No signing or verifying key is configured, or the key file it names is not there.

The bundle builds and boots without a key, so the console stays usable to mint one; the absence is reported here, the first time a token is signed or verified. It is a deployment's mistake, never a client's: the encoder lets it through rather than reporting it as a token that failed to verify, so a request meeting it fails as a server error instead of a 401.

Attributes:

  • location (str | None) –

    The key file that was looked for, or None when no key is configured at all.

Record the key file looked for, or that no key is configured at all.

MissingTokenError

MissingTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)

Bases: AuthenticationError

A request reached a protected resource carrying no token at all.

Raised by the authenticator's entry point when a firewall needs authentication and no extractor found a token, so the challenge names that the token was missing rather than wrong.