GitHub

API reference for jwt.

JSON Web Tokens (Effect's effect/jose/Jwt): claims described by a schema, signed as a JWS or encrypted as a JWE::

token = yield from jwt.sign(Claims, {"sub": "user_1", "role": "admin"}, key)
verified = yield from jwt.verify(Claims, token, key, issuer="https://issuer.example")

Verifying checks the registered claims (iss, sub, aud, exp, nbf, iat, jti) before the application schema decodes the claims: each must have its registered type, and the options say which are required and what they must be. exp and nbf are always checked against the Clock, within clock_tolerance; max_token_age bounds the age iat gives.

Re-exports

Values

AttributeTypeDescription
RegisteredClaimsSchemaStructSchema[RegisteredClaims, Never, Never]

Types

TypeDefinitionDescription
RegisteredClaimtype RegisteredClaim = Literal['iss', 'sub', 'aud', 'exp', 'nbf', 'iat', 'jti']
JwtErrortype JwtError = JoseError | SchemaError

Classes

Functions

sign

sign[A, R](schema: Exact[A, Any, R], claims: A, key: HmacKey, header: Header | None = None) -> Effect[Redacted[str], JwtError, R | Mac]
sign[A, R](schema: Exact[A, Any, R], claims: A, key: PrivateKey, header: Header | None = None) -> Effect[Redacted[str], JwtError, R | Signature]
sign[A, R](schema: Exact[A, Any, R], claims: A, key: SigningKey, header: Header | None = None) -> Effect[Redacted[str], JwtError, R | Mac | Signature]

The claims, encoded by schema, as a signed JWT. claims has the schema's Type, and their encoding must be a JSON object whose registered claims have their types.

ParameterTypeDescription
schema
claims
key
header= None
@overload
def sign[A, R](
    schema: Exact[A, Any, R], claims: A, key: HmacKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Mac]: ...
@overload
def sign[A, R](
    schema: Exact[A, Any, R], claims: A, key: PrivateKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Signature]: ...
@overload
def sign[A, R](
    schema: Exact[A, Any, R], claims: A, key: SigningKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Mac | Signature]: ...
def sign(
    schema: Exact[Any, Any, Any], claims: Any, key: SigningKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, Any]:
    """The claims, encoded by ``schema``, as a signed JWT. ``claims`` has the
    schema's Type, and their encoding must be a JSON object whose registered
    claims have their types."""
    return _encode_claims(schema, claims).flat_map(lambda payload: jws.sign(payload, key, header))

verify

verify[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: HmacKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Verified[A], JwtError, R | Mac]
verify[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: PublicKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Verified[A], JwtError, R | Signature]
verify[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: VerificationKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Verified[A], JwtError, R | Mac | Signature]

The claims of a JWT signed with key, checked against options and decoded by schema.

ParameterTypeDescription
schema
token
key
options= {}
@overload
def verify[A, R](
    schema: S.Codec[A, Any, R, Any], token: Token, key: HmacKey, **options: Unpack[VerifyOptions]
) -> Effect[Verified[A], JwtError, R | Mac]: ...
@overload
def verify[A, R](
    schema: S.Codec[A, Any, R, Any], token: Token, key: PublicKey, **options: Unpack[VerifyOptions]
) -> Effect[Verified[A], JwtError, R | Signature]: ...
@overload
def verify[A, R](
    schema: S.Codec[A, Any, R, Any],
    token: Token,
    key: VerificationKey,
    **options: Unpack[VerifyOptions],
) -> Effect[Verified[A], JwtError, R | Mac | Signature]: ...
def verify(
    schema: S.Codec[Any, Any, Any, Any],
    token: Token,
    key: VerificationKey,
    **options: Unpack[VerifyOptions],
) -> Effect[Verified[Any], JwtError, Any]:
    """The claims of a JWT signed with ``key``, checked against ``options``
    and decoded by ``schema``."""

    @gen
    def body():
        policy = yield from _read_policy(options)
        verified = yield from jws.verify(token, key)
        claims, registered = yield from _decode_claims(
            schema,
            verified.payload,
            cast("Mapping[str, object]", verified.protected_header),
            policy,
        )
        return Verified(claims, registered, verified.protected_header)

    return body

verify_with_key_set

verify_with_key_set[A, R](schema, token, *, algorithms, **options) -> Effect[VerifiedWithKey[A], JwtError, R | Jwks | Signature]

verify with the Jwks key the header selects, for an alg in algorithms.

ParameterTypeDescription
schemaS.Codec[A, Any, R, Any]
tokenToken
algorithmsSequence[AsymmetricAlgorithm]
optionsUnpack[VerifyOptions] = {}

Returns Effect[VerifiedWithKey[A], JwtError, R | Jwks | Signature]

def verify_with_key_set[A, R](
    schema: S.Codec[A, Any, R, Any],
    token: Token,
    *,
    algorithms: Sequence[AsymmetricAlgorithm],
    **options: Unpack[VerifyOptions],
) -> Effect[VerifiedWithKey[A], JwtError, R | Jwks | Signature]:
    """``verify`` with the ``Jwks`` key the header selects, for an ``alg`` in
    ``algorithms``."""

    @gen
    def body():
        policy = yield from _read_policy(options)
        verified = yield from jws.verify_with_key_set(token, algorithms=algorithms)
        claims, registered = yield from _decode_claims(
            schema,
            verified.payload,
            cast("Mapping[str, object]", verified.protected_header),
            policy,
        )
        return VerifiedWithKey(claims, registered, verified.protected_header, verified.key)

    return body

encrypt

encrypt[A, R](schema, claims, key, header=None) -> Effect[Redacted[str], JwtError, R | Aead | SecureRandom]

The claims, encoded by schema, as an encrypted JWT. claims has the schema's Type.

ParameterTypeDescription
schemaExact[A, Any, R]
claimsA
keyDirKey
headerHeader | None = None

Returns Effect[Redacted[str], JwtError, R | Aead | SecureRandom]

def encrypt[A, R](
    schema: Exact[A, Any, R], claims: A, key: DirKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Aead | SecureRandom]:
    """The claims, encoded by ``schema``, as an encrypted JWT. ``claims`` has
    the schema's Type."""
    return _encode_claims(schema, claims).flat_map(
        lambda payload: jwe.encrypt(payload, key, header)
    )

decrypt

decrypt[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: DirKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Decrypted[A], JwtError, R | Aead]
decrypt[A, R, E = Never, R2 = Never](schema: S.Codec[A, Any, R, Any], token: Token, key: Callable[[jwe.ProtectedHeader], Effect[DirKey, E, R2]], **options: Unpack[VerifyOptions] = {}) -> Effect[Decrypted[A], JwtError | E, R | Aead | R2]

The claims of an encrypted JWT, checked against options and decoded by schema.

ParameterTypeDescription
schema
token
key
options= {}
@overload
def decrypt[A, R](
    schema: S.Codec[A, Any, R, Any], token: Token, key: DirKey, **options: Unpack[VerifyOptions]
) -> Effect[Decrypted[A], JwtError, R | Aead]: ...
@overload
def decrypt[A, R, E = Never, R2 = Never](
    schema: S.Codec[A, Any, R, Any],
    token: Token,
    key: Callable[[jwe.ProtectedHeader], Effect[DirKey, E, R2]],
    **options: Unpack[VerifyOptions],
) -> Effect[Decrypted[A], JwtError | E, R | Aead | R2]: ...
def decrypt(
    schema: S.Codec[Any, Any, Any, Any],
    token: Token,
    key: DirKey | Callable[[jwe.ProtectedHeader], Effect[DirKey, Any, Any]],
    **options: Unpack[VerifyOptions],
) -> Effect[Decrypted[Any], Any, Any]:
    """The claims of an encrypted JWT, checked against ``options`` and
    decoded by ``schema``."""

    @gen
    def body():
        policy = yield from _read_policy(options)
        decrypted = yield from jwe.decrypt(token, key)
        claims, registered = yield from _decode_claims(
            schema,
            decrypted.plaintext,
            cast("Mapping[str, object]", decrypted.protected_header),
            policy,
        )
        return Decrypted(claims, registered, decrypted.protected_header, decrypted.key)

    return body

decode_unverified

decode_unverified(token) -> Effect[Unverified, JoseError]

A signed JWT's header and claims, without verifying anything.

ParameterTypeDescription
tokenToken

Returns Effect[Unverified, JoseError]

def decode_unverified(token: Token) -> Effect[Unverified, JoseError]:
    """A signed JWT's header and claims, without verifying anything."""

    @gen
    def body():
        parsed = yield from jws.parse(token)
        claims = parse_json_object(parsed.payload)
        if claims is None:
            return (yield from invalid_token("The JWT payload is not a JSON object"))
        return Unverified(parsed.protected_header, claims)

    return body