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.
JWTStronly 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 layerJWTStr/JWTConstraintson top for schema-level sanity checks.
Requirements
- Python >= 3.10
- Pydantic >= 2.10.0
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pydantic_jwt-0.1.1.tar.gz.
File metadata
- Download URL: pydantic_jwt-0.1.1.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
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ec95f07cb2781de6e6ced539db274edec4fd2875356daf08fb85861230bdf18d
|
|
| MD5 |
15bdce86136457eba08310d6446dff55
|
|
| BLAKE2b-256 |
cc3dffafb6807567de728b5d07c230e96b7c26670f2065d28232c8616b234d0e
|
Provenance
The following attestation bundles were made for pydantic_jwt-0.1.1.tar.gz:
Publisher:
publish.yml on dmi03/pydantic-jwt
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pydantic_jwt-0.1.1.tar.gz -
Subject digest:
ec95f07cb2781de6e6ced539db274edec4fd2875356daf08fb85861230bdf18d - Sigstore transparency entry: 2581250742
- Sigstore integration time:
-
Permalink:
dmi03/pydantic-jwt@100c84436c09919962d8817869e125b89b06d6f0 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/dmi03
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@100c84436c09919962d8817869e125b89b06d6f0 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file pydantic_jwt-0.1.1-py3-none-any.whl.
File metadata
- Download URL: pydantic_jwt-0.1.1-py3-none-any.whl
- Upload date:
- Size: 6.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1e86eee8990550822fb6a00f11c9d46a8ccc13d869ebee987c3478b6bb82a802
|
|
| MD5 |
e3b3d371e3f65c48432e6862f06c9cc2
|
|
| BLAKE2b-256 |
f28b430823689acfb71bf9949894a59ec3a6c18d261296e2e986e1136033933f
|
Provenance
The following attestation bundles were made for pydantic_jwt-0.1.1-py3-none-any.whl:
Publisher:
publish.yml on dmi03/pydantic-jwt
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pydantic_jwt-0.1.1-py3-none-any.whl -
Subject digest:
1e86eee8990550822fb6a00f11c9d46a8ccc13d869ebee987c3478b6bb82a802 - Sigstore transparency entry: 2581250756
- Sigstore integration time:
-
Permalink:
dmi03/pydantic-jwt@100c84436c09919962d8817869e125b89b06d6f0 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/dmi03
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@100c84436c09919962d8817869e125b89b06d6f0 -
Trigger Event:
workflow_dispatch
-
Statement type:
