Skip to main content
# PyJWT [![Build Status](https://travis-ci.org/progrium/pyjwt.png?branch=master)](https://travis-ci.org/progrium/pyjwt)

A Python implementation of [JSON Web Token draft 01](http://self-issued.info/docs/draft-jones-json-web-token-01.html).

## Installing

```
$ pip install PyJWT
```

**A Note on Dependencies**:

The RSASSA-PKCS1-v1_5 algorithms depend on PyCrypto. If you plan on
using any of those algorithms, you'll need to install it as well.

```
$ pip install PyCrypto
```

The Elliptic Curve Digital Signature algorithms depend on Python-ECDSA. If
you plan on using any of those algorithms, you'll need to install it as well.

```
$ pip install ecdsa
```

## Usage

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

Additional headers may also be specified.

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

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

```python
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`.

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

## Algorithms

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:

```python
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 an RSA public or private key as imported with `Crypto.PublicKey.RSA.importKey()`.

When using the ECDSA algorithms, the `key` argument is expected to
be an Elliptic Curve private key as imported with `ecdsa.SigningKey.from_pem()`,
or a public key as imported with `ecdsa.VerifyingKey.from_pem()`.

## Tests

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

```
$ python tests/test_jwt.py
```

## 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](http://self-issued.info/docs/draft-jones-json-web-token-01.html#ReservedClaimName):

> 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/time listed in the exp claim. Implementers MAY provide for some small
> leeway, usually no more than a few minutes, to account for clock skew. Its
> value MUST be a number containing an IntDate value. Use of this claim is
> OPTIONAL.

You can pass the expiration time as a UTC UNIX timestamp (an int) or as a
datetime, which will be converted into an int. For example:

```python
jwt.encode({'exp': 1371720939}, 'secret')

jwt.encode({'exp': datetime.utcnow()}, 'secret')
```

Expiration time is automatically verified in `jwt.decode()` and raises
`jwt.ExpiredSignature` if the expiration time is in the past:

```python
import jwt

try:
jwt.decode('JWT_STRING', 'secret')
except jwt.ExpiredSignature:
# Signature has expired
```

Expiration time will be compared to the current UTC time (as given by
`timegm(datetime.utcnow().utctimetuple())`), so be sure to use a UTC timestamp
or datetime in encoding.

You can turn off expiration time verification with the `verify_expiration` argument.

PyJWT also supports the leeway part of the expiration time definition, which
means you can validate a expiration time which is in the past but not very far.
For example, if you have a JWT payload with a expiration time set to 30 seconds
after creation but you know that sometimes you will process it after 30 seconds,
you can set a leeway of 10 seconds in order to have some margin:

```python
import datetime
import time
import jwt

jwt_payload = jwt.encode({
'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=30)
}, 'secret')

time.sleep(32)

# JWT payload is now expired
# But with some leeway, it will still validate
jwt.decode(jwt_payload, 'secret', leeway=10)
```

### Not Before Time Claim

> The nbf (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. The processing of the nbf claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the nbf claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value. Use of this claim is OPTIONAL.

The `nbf` claim works similarly to the `exp` claim above.

```python
jwt.encode({'nbf': 1371720939}, 'secret')

jwt.encode({'nbf': datetime.utcnow()}, 'secret')
```

### Issuer Claim

> The iss (issuer) claim identifies the principal that issued the JWT. The processing of this claim is generally application specific. The iss value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL.

```python
import jwt


payload = {
'some': 'payload',
'iss': 'urn:foo'
}

token = jwt.encode(payload, 'secret')
decoded = jwt.decode(token, 'secret', issuer='urn:foo')
```

### Audience Claim

> The aud (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the aud claim when this claim is present, then the JWT MUST be rejected. In the general case, the aud value is an array of case-sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the aud value MAY be a single case-sensitive string containing a StringOrURI value. The interpretation of audience values is generally application specific. Use of this claim is OPTIONAL.

```python
import jwt


payload = {
'some': 'payload',
'aud': 'urn:foo'
}

token = jwt.encode(payload, 'secret')
decoded = jwt.decode(token, 'secret', audience='urn:foo')
```

## License

MIT

Metadata

Release files for PyJWT 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for PyJWT 0.3.0
File Size Uploaded Provenance Actions
PyJWT-0.3.0.tar.gz 8.1 kB Without provenance Details for PyJWT-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for PyJWT 0.3.0
File Interpreter ABI Platform Actions
PyJWT-0.3.0-py2.py3-none-any.whl Python 3, Python 2 none any Details for PyJWT-0.3.0-py2.py3-none-any.whl

Total release size: 19.5 kB

Release files / PyJWT-0.3.0.tar.gz

Download URL PyJWT-0.3.0.tar.gz
Size 8.1 kB
Tags Source
SHA-256 checksum
How to use checksums
040ce47ef091e7030ec9490633e0c3c768ab9bc4e820477f2edd5736bb87a347
BLAKE2b-256 checksum
How to use checksums
221014605dc0c5626b199bfa61a2a8dbcbf1c430a6f25f5e62cb26e2ce1b53bb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / PyJWT-0.3.0-py2.py3-none-any.whl

Download URL PyJWT-0.3.0-py2.py3-none-any.whl
Size 11.4 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
8deabbbb4bf7ed5fed5ad59b3a5167e781ff888e21ee29982a4b20130f4ed15d
BLAKE2b-256 checksum
How to use checksums
a8196071c816ac61a4b3923b7d34617db0f0a5031f2aae383949fef89b9d7ef1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for PyJWT 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page