0
# PyJWT
1

2
A comprehensive Python library for JSON Web Token (JWT) implementation providing secure token-based authentication and authorization. PyJWT supports complete RFC 7519 standard with encoding, decoding, and validation using various cryptographic algorithms including HMAC, RSA, ECDSA, and EdDSA signatures.
3

4
## Package Information
5

6
- **Package Name**: PyJWT
7
- **Language**: Python
8
- **Installation**: `pip install PyJWT` (basic HMAC) or `pip install PyJWT[crypto]` (full cryptographic support)
9

10
## Core Imports
11

12
```python
13
import jwt
14
```
15

16
Common usage imports:
17

18
```python
19
from jwt import encode, decode, PyJWT
20
from jwt.exceptions import InvalidTokenError, ExpiredSignatureError
21
```
22

23
## Basic Usage
24

25
```python
26
import jwt
27
from datetime import datetime, timedelta, timezone
28

29
# Encode a JWT
30
payload = {
31
    'user_id': 123,
32
    'exp': datetime.now(tz=timezone.utc) + timedelta(hours=1)
33
}
34
token = jwt.encode(payload, 'your-secret-key', algorithm='HS256')
35

36
# Decode and verify a JWT
37
try:
38
    decoded = jwt.decode(token, 'your-secret-key', algorithms=['HS256'])
39
    print(f"User ID: {decoded['user_id']}")
40
except jwt.ExpiredSignatureError:
41
    print("Token has expired")
42
except jwt.InvalidTokenError:
43
    print("Invalid token")
44
```
45

46
## Architecture
47

48
PyJWT provides a layered architecture for JWT operations:
49

50
- **JWT Layer**: High-level JWT encoding/decoding with claim validation (PyJWT class)
51
- **JWS Layer**: Lower-level JSON Web Signature operations (PyJWS class)
52
- **JWK Layer**: JSON Web Key handling and cryptographic key abstraction (PyJWK, PyJWKSet)
53
- **JWKS Client**: HTTP client for fetching and caching remote key sets (PyJWKClient)
54
- **Algorithm Support**: Pluggable cryptographic algorithm system with HMAC, RSA, ECDSA, EdDSA
55

56
This design enables secure token operations across web frameworks, API services, and microservices with comprehensive claim validation, flexible key management, and extensive algorithm support.
57

58
## Capabilities
59

60
### JWT Operations
61

62
Core JWT encoding and decoding functionality with automatic claim validation, expiration checking, and signature verification. Supports standard claims (exp, nbf, iat, aud, iss, sub) and custom payloads.
63

64
```python { .api }
65
def encode(payload: dict, key: str | bytes, algorithm: str = 'HS256', 
66
          headers: dict = None, json_encoder = None) -> str: ...
67
def decode(jwt: str | bytes, key: str | bytes = '', algorithms: list = None,
68
          options: dict = None, audience: str = None, issuer: str = None,
69
          leeway: float = 0) -> dict: ...
70
class PyJWT:
71
    def __init__(self, options: dict = None): ...
72
    def encode(self, payload: dict, key, algorithm: str = None, 
73
              headers: dict = None) -> str: ...
74
    def decode(self, jwt: str | bytes, key = '', algorithms: list = None,
75
              options: dict = None) -> dict: ...
76
```
77

78
[JWT Operations](./jwt-operations.md)
79

80
### JWS Operations
81

82
Lower-level JSON Web Signature operations for signing and verifying arbitrary payloads. Provides direct access to the signature layer without JWT-specific claim validation.
83

84
```python { .api }
85
class PyJWS:
86
    def __init__(self, algorithms: list = None, options: dict = None): ...
87
    def encode(self, payload: bytes, key, algorithm: str = None,
88
              headers: dict = None) -> str: ...
89
    def decode(self, jws: str | bytes, key = '', algorithms: list = None,
90
              options: dict = None) -> bytes: ...
91
    def get_unverified_header(self, jwt: str | bytes) -> dict: ...
92
```
93

94
[JWS Operations](./jws-operations.md)
95

96
### JSON Web Keys (JWK)
97

98
JSON Web Key handling and cryptographic key abstraction supporting RSA, ECDSA, EdDSA, and symmetric keys. Provides key parsing, validation, and algorithm detection.
99

100
```python { .api }
101
class PyJWK:
102
    def __init__(self, jwk_data: dict, algorithm: str = None): ...
103
    @staticmethod
104
    def from_dict(obj: dict, algorithm: str = None) -> 'PyJWK': ...
105
    @staticmethod  
106
    def from_json(data: str, algorithm: str = None) -> 'PyJWK': ...
107
    @property
108
    def key_type(self) -> str: ...
109
    @property
110
    def key_id(self) -> str: ...
111

112
class PyJWKSet:
113
    def __init__(self, keys: list): ...
114
    @staticmethod
115
    def from_dict(obj: dict) -> 'PyJWKSet': ...
116
    @staticmethod
117
    def from_json(data: str) -> 'PyJWKSet': ...
118
    def __getitem__(self, kid: str) -> PyJWK: ...
119
```
120

121
[JSON Web Keys](./jwk-operations.md)
122

123
### JWKS Client
124

125
HTTP client for fetching and caching JSON Web Key Sets from remote endpoints. Supports automatic key refresh, caching strategies, and integration with JWT verification.
126

127
```python { .api }
128
class PyJWKClient:
129
    def __init__(self, uri: str, cache_keys: bool = False, 
130
                max_cached_keys: int = 16, cache_jwk_set: bool = True,
131
                lifespan: int = 300, headers: dict = None, 
132
                timeout: int = 30): ...
133
    def get_signing_key(self, kid: str) -> PyJWK: ...
134
    def get_signing_key_from_jwt(self, token: str) -> PyJWK: ...
135
    def get_jwk_set(self, refresh: bool = False) -> PyJWKSet: ...
136
```
137

138
[JWKS Client](./jwks-client.md)
139

140
### Algorithm Management
141

142
Cryptographic algorithm registration and management system supporting custom algorithms and algorithm whitelisting for security.
143

144
```python { .api }
145
def register_algorithm(alg_id: str, alg_obj) -> None: ...
146
def unregister_algorithm(alg_id: str) -> None: ...
147
def get_algorithm_by_name(alg_name: str): ...
148
def get_unverified_header(jwt: str | bytes) -> dict: ...
149
```
150

151
[Algorithm Management](./algorithm-management.md)
152

153
## Exception Types
154

155
```python { .api }
156
class PyJWTError(Exception):
157
    """Base class for all PyJWT exceptions"""
158

159
class InvalidTokenError(PyJWTError):
160
    """Invalid token format or structure"""
161

162
class DecodeError(InvalidTokenError):
163
    """Token parsing or decoding errors"""
164

165
class InvalidSignatureError(DecodeError):
166
    """Signature verification failed"""
167

168
class ExpiredSignatureError(InvalidTokenError):
169
    """Token has expired (exp claim)"""
170

171
class ImmatureSignatureError(InvalidTokenError):
172
    """Token not yet valid (nbf/iat claims)"""
173

174
class InvalidAudienceError(InvalidTokenError):
175
    """Audience claim validation failed"""
176

177
class InvalidIssuerError(InvalidTokenError):
178
    """Issuer claim validation failed"""
179

180
class MissingRequiredClaimError(InvalidTokenError):
181
    """Required claim missing from token"""
182

183
class InvalidSubjectError(InvalidTokenError):
184
    """Subject claim validation failed"""
185

186
class InvalidJTIError(InvalidTokenError):
187
    """JWT ID claim validation failed"""
188

189
class PyJWKError(PyJWTError):
190
    """JSON Web Key related errors"""
191

192
class MissingCryptographyError(PyJWKError):
193
    """Cryptography library required for asymmetric algorithms"""
194

195
class PyJWKClientError(PyJWTError):
196
    """JWKS client errors"""
197
```