Skip to content

Latest commit

 

History

History
105 lines (64 loc) · 3.55 KB

api.rst

File metadata and controls

105 lines (64 loc) · 3.55 KB
Raw

API Reference

jwt

encode(payload, key, algorithm="HS256", headers=None, json_encoder=None)

Encode the payload as JSON Web Token.

param dict payload

JWT claims, e.g. dict(iss=..., aud=..., sub=...)

param str key

a key suitable for the chosen algorithm:

  • for asymmetric algorithms: PEM-formatted private key, a multiline string
  • for symmetric algorithms: plain string, sufficiently long for security
param str algorithm

algorithm to sign the token with, e.g. "ES256"

param dict headers

additional JWT header fields, e.g. dict(kid="my-key-id")

param json.JSONEncoder json_encoder

custom JSON encoder for payload and headers

rtype

str

returns

a JSON Web Token

decode(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0)

Verify the jwt token signature and return the token claims.

param str|bytes jwt

the token to be decoded

param str key

the key suitable for the allowed algorithm

param list algorithms

allowed algorithms, e.g. ["ES256"]

Note

It is highly recommended to specify the expected algorithms.

Note

It is insecure to mix symmetric and asymmetric algorithms because they require different kinds of keys.

param dict options

extended decoding and validation options

  • require_exp=False check that exp (expiration) claim is present
  • require_iat=False check that iat (issued at) claim is present
  • require_nbf=False check that nbf (not before) claim is present
  • verify_aud=False check that aud (audience) claim matches audience
  • verify_iat=False check that iat (issued at) claim value is an integer
  • verify_exp=False check that exp (expiration) claim value is OK
  • verify_iss=False check that iss (issuer) claim matches issuer
  • verify_signature=True verify the JWT cryptographic signature
param iterable audience

optional, the value for verify_aud check

param str issuer

optional, the value for verify_iss check

param int|float leeway

a time margin in seconds for the expiration check

rtype

dict

returns

the JWT claims

Note

TODO: Document PyJWS / PyJWT classes

Exceptions

jwt.exceptions

Base exception when decode() fails on a token

Raised when a token cannot be decoded because it failed validation

Raised when a token's signature doesn't match the one provided as part of the token.

Raised when a token's exp claim indicates that it has expired

Raised when a token's aud claim does not match one of the expected audience values

Raised when a token's iss claim does not match the expected issuer

Raised when a token's iat claim is in the future

Raised when a token's nbf claim represents a time in the future

Raised when the specified key is not in the proper format

Raised when the specified algorithm is not recognized by PyJWT

Raised when a claim that is required to be present is not contained in the claimset