fastjwt-kit 0.1.0

A small, opinionated JWT toolkit: create, verify, expire, and handle errors without writing the same PyJWT boilerplate every project.

fastjwt-kit

A small, opinionated wrapper around PyJWT that handles the boilerplate every project rewrites: token creation, expiry, claim validation, and clean error handling — without you having to import jwt exceptions directly.

Install

pip install fastjwt-kit

Quickstart

from fastjwt_kit import create_access_token, verify_token, TokenExpiredError

token = create_access_token(subject="user-123", secret="change-me")

try:
    claims = verify_token(token, secret="change-me")
    print(claims["sub"])  # "user-123"
except TokenExpiredError:
    print("Token expired — ask the user to log in again")

That's it — no manual exp math, no catching raw jwt.ExpiredSignatureError.

Access + refresh tokens

from fastjwt_kit import create_access_token, create_refresh_token

access = create_access_token(subject="user-123", secret="change-me")          # 15 min default
refresh = create_refresh_token(subject="user-123", secret="change-me")        # 7 days default

Custom expiry, issuer, audience, and extra claims

import datetime as dt
from fastjwt_kit import create_token, verify_token

token = create_token(
    subject="user-123",
    secret="change-me",
    expires_in=dt.timedelta(hours=1),
    issuer="my-app",
    audience="my-app-clients",
    extra_claims={"role": "admin"},
)

claims = verify_token(token, secret="change-me", issuer="my-app", audience="my-app-clients")

Error handling

All errors inherit from TokenError, so you can catch broadly or specifically:

from fastjwt_kit import TokenError, TokenExpiredError, InvalidTokenError, InvalidClaimsError

try:
    claims = verify_token(token, secret="change-me")
except TokenExpiredError:
    ...  # token was valid but has expired
except InvalidClaimsError:
    ...  # issuer/audience didn't match
except InvalidTokenError:
    ...  # malformed or tampered token
except TokenError:
    ...  # catch-all

API

Function	Description
create_token(subject, secret, *, expires_in, ...)	Create a JWT with full control over claims.
create_access_token(subject, secret, ...)	Create a short-lived token (default 15 min), tagged type: access.
create_refresh_token(subject, secret, ...)	Create a long-lived token (default 7 days), tagged type: refresh.
verify_token(token, secret, *, algorithm, issuer, audience)	Decode and validate a token, raising fastjwt_kit exceptions.

Why not just use PyJWT directly?

You can! This package just wraps the parts everyone ends up rewriting: expiry defaults, issuer/audience checks, and exception types that don't leak the underlying library. If you only need raw encode/decode, PyJWT alone is enough.

Roadmap

• Password hashing module
• FastAPI signup/login router + get_current_user dependency
• Config/env validation helpers

Feedback and issues welcome — this is an early release and will evolve based on real usage.

License

MIT