pydantic-jwt

Structural JWT validation as a Pydantic type.

pydantic-jwt gives you a JWTStr type that validates a string is a well-formed JSON Web Token (RFC 7519) — three base64url segments, valid JSON header/payload, and a non-empty alg. It does not verify the cryptographic signature; use it to catch malformed tokens early, at the schema layer, before doing real verification with a library like PyJWT.

Install

pip install pydantic-jwt

Basic usage

from pydantic import BaseModel
from pydantic_jwt import JWTStr


class Auth(BaseModel):
    token: JWTStr


auth = Auth(token="eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dGVzdA")

print(auth.token.header)  # {'alg': 'HS256'}
print(auth.token.payload)  # {'sub': '1234567890'}
print(auth.token.algorithm)  # 'HS256'
print(auth.token.signature)  # b'test'

If the string isn't a valid JWT, Pydantic raises a normal ValidationError:

Auth(token="not-a-jwt")
# pydantic_core._pydantic_core.ValidationError: 1 validation error for Auth
# token
#   Value must include header, payload, and signature separated by dots [type=jwt_format, ...]

Additional constraints

For extra checks beyond structural validity — allowed algorithms, token expiry (exp), not-before (nbf) — use JWTConstraints with Annotated:

from typing import Annotated

from pydantic import BaseModel
from pydantic_jwt import JWTStr, JWTConstraints


class Auth(BaseModel):
    token: Annotated[
        JWTStr,
        JWTConstraints(allowed_algorithms=("HS256", "RS256")),
    ]

By default, JWTConstraints() rejects expired tokens (exp in the past) and tokens that aren't active yet (nbf in the future).

JWTConstraints options

Field Default Description
allowed_algorithms None Tuple of allowed alg values. None allows any algorithm.
exp_name "exp" Payload key used for the expiry check.
allow_exp False If True, skip the expiry check entirely.
nbf_name "nbf" Payload key used for the not-before check.
allow_nbf False If True, skip the not-before check entirely. 
# allow expired tokens, only restrict algorithm
token: Annotated[JWTStr, JWTConstraints(allowed_algorithms=("HS256",), allow_exp=True)]

# use non-standard claim names
token: Annotated[JWTStr, JWTConstraints(exp_name="expires_at", nbf_name="not_before")]

What this does not do

  • No signature verification. JWTStr only checks structure, not authenticity. Anyone can craft a structurally valid JWT with any payload they like — never trust claims from an unverified token.
  • No decoding shortcuts for auth. For real authentication flows, verify the signature with a dedicated library (e.g. PyJWT, python-jose) using the correct key and algorithm, then optionally layer JWTStr/JWTConstraints on top for schema-level sanity checks.

Requirements

  • Python >= 3.10
  • Pydantic >= 2.10.0

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dmi03 from gravatar.com dmi03

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: dmi03

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydantic_jwt-0.1.0.tar.gz (64.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pydantic_jwt-0.1.0-py3-none-any.whl (6.1 kB view details)

Uploaded Python 3

File details

Details for the file pydantic_jwt-0.1.0.tar.gz.

File metadata

  • Download URL: pydantic_jwt-0.1.0.tar.gz
  • Upload date:
  • Size: 64.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydantic_jwt-0.1.0.tar.gz
Algorithm Hash digest
SHA256 4f15a4b78d17a2d1f62dd52d0641c79b8c81ec096af7d4478860c2d234393621
MD5 af63250dcf056b73027679546854217b
BLAKE2b-256 a2ddc1e9f44262ed6ef9956bbd97027e4f6b0cecb2da8f5ec5caf5f09f0e83ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydantic_jwt-0.1.0.tar.gz:

Publisher: publish.yml on dmi03/pydantic-jwt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydantic_jwt-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: pydantic_jwt-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 6.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydantic_jwt-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 51f7ff3f9a5f8002576c6a307b5114194bf99818ae160cd4bf87a6a9dd3858ec
MD5 6652cc8c8ad0551c96b04bd62d314151
BLAKE2b-256 b68a17f57b034c1457925e3fcc398c5575b5c45d38e5daf3615e4d90b844e99d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydantic_jwt-0.1.0-py3-none-any.whl:

Publisher: publish.yml on dmi03/pydantic-jwt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.0

2 files

0.1.1

2 files

This release

0.1.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page