> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add custom claims

> Encode additional information into your session JWTs using custom claims.

## 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:

```python theme={null}
# 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:

```python theme={null}
# 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}
```

> [accordion] 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:
>
> ```python theme={null}
> 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](https://stytch.com/dashboard/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 }}`

> [accordion] Example
>
> The template:
>
> ```json theme={null}
> {
>   "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:
>
> ```json theme={null}
> {
>   "member_id": "member-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
>   "trusted_metadata": {
>     "custom_key": "custom-value"
>   }
> }
> ```
>
> to produce the final set of custom claims:
>
> ```json theme={null}
> {
>   "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.
