Install & Compatibility
Where this runs
tested against v0.12.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.414s · 35.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.408s · 36MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Jwk
✓ from jwskate import Jwk
Jwt
✓ from jwskate import Jwt
Jws
✓ from jwskate import Jws
Jwe
✓ from jwskate import Jwe
SymmetricJwk
✓ from jwskate import SymmetricJwk
InvalidSignature
✓ from jwskate import InvalidSignature
This quickstart demonstrates how to generate an RSA key pair, sign a JSON Web Token (JWT) with the private key, and then verify its signature using the corresponding public key. It highlights the importance of specifying the expected algorithm during verification.
from jwskate import Jwk, Jwt, InvalidSignature
# 1. Generate a private RSA key for signing
private_jwk = Jwk.generate(alg="RS256", key_size=2048, kid="my-rsa-key")
public_jwk = private_jwk.public_jwk()
# 2. Define claims for the JWT
claims = {"sub": "user123", "name": "John Doe", "iat": 1678886400, "exp": 1678890000}
# 3. Sign the JWT
try:
signed_jwt = Jwt.sign(claims, private_jwk)
print(f"Signed JWT: {signed_jwt.compact()}")
except Exception as e:
print(f"Error signing JWT: {e}")
exit(1)
# 4. Verify the JWT signature (using the public key)
try:
# The verify_signature method requires the expected algorithm for security
if signed_jwt.verify_signature(public_jwk, alg="RS256"):
print("JWT signature is valid!")
print(f"Decoded claims: {signed_jwt.claims}")
assert signed_jwt.claims == claims
else:
print("JWT signature verification failed.")
except InvalidSignature:
print("Invalid signature detected!")
except Exception as e:
print(f"Error verifying JWT: {e}")
Errors
Common errors & fixes
jwskate.jwt.base.InvalidJwt: Invalid JWT header: it must be a Base64URL-encoded JSON object.
This error occurs when the JWT string provided to the `Jwt` constructor has a malformed header, meaning it's either not a valid Base64URL-encoded string or doesn't decode into a valid JSON object.
fixEnsure the JWT string is correctly formatted according to the JWT Compact Serialization rules (Base64URL-encoded header, payload, and signature, separated by dots).
jwskate.jwt.base.InvalidSignature: Invalid signature
This is a common error indicating that the JWT's signature verification failed. In `jwskate`, a primary reason for this is often not explicitly providing the expected signature algorithm(s) during verification, as the library ignores the 'alg' header in the token for security reasons to prevent 'none' algorithm attacks.
fixAlways pass the expected algorithm(s) (e.g., `alg="RS256"` or `algs=["ES256", "ES384"]`) to `verify_signature` or similar methods, in addition to the verification key.
TypeError: Object of type Jwk is not JSON serializable
Jwk, Jwt, Jws, and Jwe objects in `jwskate` are subclasses of `collections.UserDict` (or `dict`), but they are not natively JSON serializable using Python's default `json.dumps()` method.
fixUse the `.to_json()` method provided by `jwskate` objects, or convert them to a standard dictionary (`dict(jwk)`) before serializing with `json.dumps()`.
jwskate.jwa.base.InvalidAlgorithm: Unsupported JOSE algorithm: A256GCM
This error indicates that the cryptographic algorithm specified for a JOSE operation (like encryption, signing, or key management) is not supported by `jwskate` for the given context or is not implemented.
fixConsult the `jwskate` documentation for the list of supported algorithms for JWS, JWE, and JWK operations and ensure the chosen algorithm is compatible with the key type and intended cryptographic operation.
Upgrade
Version history
0.12.2latest on PyPI · released Apr 2, 2025
Audit
Dependencies
cryptographyrequiredUsed for all underlying cryptographic operations.
binapyrequiredUsed for binary data manipulations.