JWT

Reference for the built-in JWT authenticator and its token classes. See the JWT guide for an overview, configuration, worked examples, and the full settings reference.

JWTAuthentication

Bases: BaseAuthentication

Bearer token authentication using JSON Web Tokens. Validates signature, expiry, issuer, and audience via PyJWT, and looks up the user via async ORM.

authenticate

authenticate(request)

Returns a (user, token) tuple for the bearer token in the Authorization header, or None when no token is supplied.

aauthenticate async

aauthenticate(request)

Returns a (user, token) tuple for the bearer token in the Authorization header, or None when no token is supplied.

authenticate_header

authenticate_header(request)

Returns the WWW-Authenticate header value used on 401 responses.

AccessToken dataclass

AccessToken(
    payload: dict = dict(),
    raw: str = "",
    token_type: str = "",
)

Bases: _Token

Short-lived bearer token sent on every authenticated request.

for_user classmethod

for_user(user) -> AccessToken

Returns a freshly signed access token for the given user.

verify classmethod

verify(raw: str) -> AccessToken

Decodes and validates the raw token, raising TokenError on any failure.

RefreshToken dataclass

RefreshToken(
    payload: dict = dict(),
    raw: str = "",
    token_type: str = "",
)

Bases: _Token

Long-lived token used to mint new access tokens without forcing the user to log in again.

access_token property

access_token: AccessToken

Returns a fresh access token derived from this refresh token's user claim.

for_user classmethod

for_user(user) -> RefreshToken

Returns a freshly signed refresh token for the given user.

verify classmethod

verify(raw: str) -> RefreshToken

Decodes and validates the raw refresh token, raising TokenError on any failure.

rotate

rotate() -> RefreshToken

Returns a fresh refresh token derived from this token's user claim.

blacklist

blacklist() -> None

Adds this token's JTI to the configured blacklist backend.

ablacklist async

ablacklist() -> None

Adds this token's JTI to the configured blacklist backend.

TokenError

Bases: Exception

Raised when a JWT cannot be decoded, has expired, or fails verification.