Adding custom claims to sessions

You can add custom claims to a Stytch session by including the session_custom_claims argument on any authenticate method. This argument takes in an arbitrary JSON object - which may be represented as a map, dictionary, or object depending on your language of choice. Custom claims are persisted on the session object and encoded in the session JWT.

To add or update a key, supply a new value.

# initial claims object {}
stytch.sessions.authenticate(token, custom_claims={"key_1": 1, "key_2": 2})
# current claims object {"key_1": 1, "key_2": 2}
stytch.sessions.authenticate(token, custom_claims={"key_1": 9})
# resulting claims object {"key_1": 9, "key_2": 2}

To delete a key, supply a null value.

# current claims object {"key_1": 1, "key_2": 2}
stytch.sessions.authenticate(token, custom_claims={"key_1": null})
# resulting claims object {"key_2": 2}

If a value for one of your custom claims is itself a JSON object, you can update and delete values in the same way.

sessions.authenticate(token, custom_claims={
    "b": null,
    "c": 3.5,
    "e": {
        "nested1": "val1",
        "nested2": "val2"
    }
})
# resulting claims object
# {
#    "c": 3.5,
#    "d": 4,
#    "e": {
#        "nested1": "val1",
#        "nested2": "val2"
#    }
# }

stytch.sessions.authenticate(token, custom_claims={
    "e": {
        "nested1": nil,
        "nested3": "val3"
    }
)
# resulting claims object
# {
#     "c": 3.5,
#     "d": 4,
#     "e": {
#         "nested2": "val2",
#         "nested3": "val3"
#     }
# }

Limitations

Certain claims are reserved and will result in an error if they are set (iss, sub, aud, exp, nbf, iat, jti, https://stytch.com/*)
Total custom claims size cannot exceed four kilobytes.