Skip to main content

​
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}
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 }}
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.