Add custom claims - Stytch Docs

Use case

Store or pass member information: Pass temporary session state or member 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}

Using nested claim objects

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 member will be used as the initial set of custom claims for all of that member’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 member 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.

Member or Organization metadata

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

Member RBAC values

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

List of supported template variables

{{ member.external_id }}
{{ member.member_id }}
{{ member.name }}
{{ member.email_address }}
{{ member.rbac.roles }}
{{ member.rbac.$RESOURCE_ID.actions }}
{{ member.trusted_metadata.$PATH }}
{{ organization.external_id }}
{{ organization.organization_id }}
{{ organization.organization_name }}
{{ organization.trusted_metadata.$PATH }}

Example

The template:

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "reader",
    "x-hasura-allowed-roles": {{ member.rbac.roles }},
    "x-hasura-user-id": {{ member.member_id }},
    "x-hasura-custom-key": {{ member.trusted_metadata.custom_key }},
    "x-hasura-organization-id": {{ organization.organization_id }}
  }
}

could be combined with the member’s information:

{
  "member_id": "member-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": "member-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "x-hasura-custom-key": "custom-value",
    "x-hasura-organization-id": "org-test-12345"
  }
}

Restrictions

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

These claims are reserved and result in an error if set:
iss sub aud exp nbf iat jti https://stytch.com/*
Total claims size cannot exceed 4kb.
A JWT cannot be modified once it is minted. You must authenticate again to update claims.

​Use case

​Add custom claims to a session

​Remove claims

​Custom claim templates

​Markup syntax

​Member or Organization metadata

​Member RBAC values

​List of supported template variables

​Restrictions