Summary
The Token.encode() method in litestar.security.jwt.Token does not allow passing additional parameters supported by the pyjwt library, such as headers. This limits flexibility when generating JWTs in projects that require including extra data in the token header (e.g., kid for selecting the correct public key during validation on the client or in another service).
Token.encode() internally uses pyjwt.encode(), but its current signature does not allow forwarding these additional arguments.
I propose to enhance the Token.encode() method to allow providing custom headers.
Basic Example
For example, in my project, token generation requires explicitly setting the kid in the header so that consumers can select the appropriate public key.
I would prefer to use the Token class provided by the framework (litestar.security.jwt.Token) instead of implementing a custom token entity, as the existing functionality already satisfies most of my needs — except for header injection.
from datetime import datetime, timedelta
from litestar.security.jwt import Token
token = Token(exp=datetime.now() + timedelta(hours=1), sub="user-id")
# Custom headers, e.g., setting 'kid' for key identification
custom_headers = {"kid": "my-key-id"}
encoded_token = token.encode(
secret="my-secret",
algorithm="HS256",
headers=custom_headers,
)# Result: we can see that the custom header has been included
print(jwt.get_unverified_header(encoded_token))
{'alg': 'HS256', 'kid': 'my-key-id', 'typ': 'JWT'}This allows consumers (e.g., client apps or services) to read the kid from the token header and select the appropriate public key for validation.
Drawbacks and Impact
The change is backward-compatible and introduces minimal complexity. It improves flexibility without adding maintenance burden, as it only forwards arguments to pyjwt.encode().
Unresolved questions
No response
Summary
The
Token.encode()method inlitestar.security.jwt.Tokendoes not allow passing additional parameters supported by thepyjwtlibrary, such as headers. This limits flexibility when generating JWTs in projects that require including extra data in the token header (e.g., kid for selecting the correct public key during validation on the client or in another service).Token.encode()internally usespyjwt.encode(), but its current signature does not allow forwarding these additional arguments.I propose to enhance the
Token.encode()method to allow providing custom headers.Basic Example
For example, in my project, token generation requires explicitly setting the kid in the header so that consumers can select the appropriate public key.
I would prefer to use the Token class provided by the framework (
litestar.security.jwt.Token) instead of implementing a custom token entity, as the existing functionality already satisfies most of my needs — except for header injection.This allows consumers (e.g., client apps or services) to read the kid from the token header and select the appropriate public key for validation.
Drawbacks and Impact
The change is backward-compatible and introduces minimal complexity. It improves flexibility without adding maintenance burden, as it only forwards arguments to
pyjwt.encode().Unresolved questions
No response