Skip to main content
Help the Python Software Foundation raise $60,000 USD by December 31st!  Building the PSF Q4 Fundraiser

JSON Web Token implementation in Python

Project description

A Python implementation of JSON Web Token draft 01.


$ pip install PyJWT

A Note on Dependencies:

RSA and ECDSA signatures depend on the cryptography package. If you plan on using any of those algorithms, you’ll need to install it as well.

$ pip install cryptography


import jwt
jwt.encode({'some': 'payload'}, 'secret')

Additional headers may also be specified.

jwt.encode({'some': 'payload'}, 'secret', headers={'kid': '230498151c214b788dd97f22b85410a5'})

Note the resulting JWT will not be encrypted, but verifiable with a secret key.

jwt.decode('someJWTstring', 'secret')

If the secret is wrong, it will raise a jwt.DecodeError telling you as such. You can still get the payload by setting the verify argument to False.

jwt.decode('someJWTstring', verify=False)


The JWT spec supports several algorithms for cryptographic signing. This library currently supports:

  • HS256 - HMAC using SHA-256 hash algorithm (default)
  • HS384 - HMAC using SHA-384 hash algorithm
  • HS512 - HMAC using SHA-512 hash algorithm
  • ES256 - ECDSA signature algorithm using SHA-256 hash algorithm
  • ES384 - ECDSA signature algorithm using SHA-384 hash algorithm
  • ES512 - ECDSA signature algorithm using SHA-512 hash algorithm
  • RS256 - RSASSA-PKCS1-v1_5 signature algorithm using SHA-256 hash algorithm
  • RS384 - RSASSA-PKCS1-v1_5 signature algorithm using SHA-384 hash algorithm
  • RS512 - RSASSA-PKCS1-v1_5 signature algorithm using SHA-512 hash algorithm

Change the algorithm with by setting it in encode:

jwt.encode({'some': 'payload'}, 'secret', 'HS512')

When using the RSASSA-PKCS1-v1_5 algorithms, the key argument in both jwt.encode() and jwt.decode() ("secret" in the examples) is expected to be either an RSA public or private key in PEM format.

When using the ECDSA algorithms, the key argument is expected to be an Elliptic Curve private key or an Elliptic Curve public key in PEM foramt.


You can run tests from the project root after cloning with:

$ python tests/

Support of reserved claim names

JSON Web Token defines some reserved claim names and defines how they should be used. PyJWT supports these reserved claim names:

  • “exp” (Expiration Time) Claim
  • “nbf” (Not Before Time) Claim
  • “iss” (Issuer) Claim
  • “aud” (Audience) Claim

Expiration Time Claim

From draft 01 of the JWT spec:

The exp (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the exp claim requires that the current date/time MUST be before the expiration date/ti

Project details

Download files

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

Files for PyJWT, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size PyJWT-0.4.0-py2.py3-none-any.whl (11.5 kB) File type Wheel Python version 2.7 Upload date Hashes View
Filename, size PyJWT-0.4.0.tar.gz (8.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page