Skip to main content

​
Use case

  • Store or pass user information: Pass temporary session state or user metadata to your application.
  • Integrate with 3rd-party services: Integrate with providers that support JWT-based authentication.
  • Implement custom authorization logic: Use custom claim templates to pass RBAC information to sessions.

​
Add custom claims to a session

Include the session_custom_claims argument on any authenticate method to add custom claims to a session. This argument takes in an arbitrary JSON object—which may be represented as a map, dictionary, or object: 
# initial claims object {}

stytch.session.authenticate(token, session_custom_claims={"key_1": 1, "key_2": 2})
# current claims object {"key_1": 1, "key_2": 2}

stytch.session.authenticate(token, session_custom_claims={"key_1": 9})
# resulting claims object {"key_1": 9, "key_2": 2}

​
Remove claims

Supply a null value to delete a key: 
# current claims object {"key_1": 1, "key_2": 2}

stytch.session.authenticate(token, session_custom_claims={"key_1": null})
# resulting claims object {"key_2": 2}
If the value of a custom claim is a JSON object, the nested values can be updated or deleted using the same methods as above:
sessions.authenticate(token, session_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.session.authenticate(token, session_custom_claims={
    "e": {
        "nested1": nil,
        "nested3": "val3"
    }
)
# resulting claims object
# {
#     "c": 3.5,
#     "d": 4,
#     "e": {
#         "nested2": "val2",
#         "nested3": "val3"
#     }
# }

​
Custom claim templates

Use custom claim templates to add the same set of claims to every session.
  • The JSON object output for a particular user will be used as the initial set of custom claims for all of that user’s sessions.
  • Claims from templates can still be added, updated, or deleted by passing in a session_custom_claims argument in an API request.
  • Updates to the custom claim template or user metadata propagate to existing sessions the next time a JWT is minted.
  • Previously minted JWTs are immutable and cannot be updated.

​
Markup syntax

Custom claim template markup language uses {{ variable }} syntax to denote information that should be passed in at runtime.

​
User metadata

Use dot notation to access nested fields when handling User metadata. For example, {{ user.trusted_metadata.subscription.level }} accesses the level field of the subscription object in the trusted_metadata on a User object.

​
User RBAC values

The variable {{ user.rbac.roles }} is evaluated as an array of all role IDs assigned to the user, e.g. ["stytch_user", "editor", "support_admin"]. The variable {{ user.rbac.$RESOURCE_ID.actions }} is evaluated as an array of all actions the user can perform on the specific resources. For example, {{ user.rbac.documents.actions }} might be evaluated as ["create", "read", "delete"].

​
List of supported template variables

  • {{ user.external_id }}
  • {{ user.user_id }}
  • {{ user.full_name }}
  • {{ user.rbac.roles }}
  • {{ user.rbac.$RESOURCE_ID.actions }}
  • {{ user.trusted_metadata.$PATH }}
The template:
{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "reader",
    "x-hasura-allowed-roles": {{ user.rbac.roles }},
    "x-hasura-user-id": {{ user.user_id }},
    "x-hasura-custom-key": {{ user.trusted_metadata.custom_key }},
  }
}
could be combined with the user’s information:
{
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "trusted_metadata": {
    "custom_key": "custom-value"
  }
}
to produce the final set of custom claims:
{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "reader",
    "x-hasura-allowed-roles": ["admin", "reader"],
    "x-hasura-user-id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "x-hasura-custom-key": "custom-value",
  }
}

​
Limitations

Both API-driven custom claims and custom claim templates share these limitations:

​
List of reserved claims

These claims are reserved and will result in an error if set:
  • iss
  • sub
  • aud
  • exp
  • nbf
  • iat
  • jti
  • https://stytch.com/*

​
Size limit

Total claims size cannot exceed 4kb.

​
JWT immutability

A JWT cannot be modified once it is minted. You must authenticate again to update claims.