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

# Configure Custom Claims for Anonymous Sessions

> Map anonymous session metadata into access token custom claims using claims mapping.

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<ReleaseStageNotice feature="Anonymous Sessions" stage="ea" plans="Enterprise" contact="your Account Executive" />

When your resource servers need additional information about a user but you are only passing along an [access token](/docs/secure/tokens/access-tokens), you can augment the access token with [custom claims](/docs/secure/tokens/json-web-tokens/create-custom-claims) to store additional data.

A common way to set a custom claim is by calling [`api.accessToken.setCustomClaim()`](/docs/actions/reference/credentials-exchange/credentials-exchange-api-object#api-accesstoken-setcustomclaim-key-value) in a [`post-login`](/docs/customize/actions/explore-triggers/post-login) Action. However, in an [anonymous sessions](/docs/manage-users/sessions/anonymous-sessions) context, there is no login, and therefore no `post-login` Action execution. This removes the opportunity to add custom claims to the access token the usual way, leaving APIs that expect those claims unable to read them.

To solve this, Auth0 provides claims mapping, which is a direct translation between an anonymous session's metadata and the access tokens issued for it. For example, given a session that contains:

```json theme={null}
{
  "user_id": "anon@1234-5678-90",
  "session_id": "sess_456",
  "metadata": {
    "language": "EN",
    "country": "US",
    "purchase": "P0123"
  }
}
```

You can configure your API to read the `language` value from every new anonymous access token it creates and include it as a custom claim called `lang`.

## Configure claims mapping

To configure claims mapping for anonymous sessions, you can use the [Auth0 Dashboard](/docs/get-started/auth0-overview/dashboard) or the [Management API](/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Navigate to [**Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis), and select the API you want to configure the claims for.

    2. Select the **Claim Mapping** tab.

           <img src="https://mintlify.s3.us-west-1.amazonaws.com/docs-dev/docs/images/sessions/anonymous_sessions/anonymous_sessions_claim_mapping.png" alt="The Application claim mapping page in the Auth0 Dashboard" />

    3. Under **Add a claim**, enter a claim **Name** (for example, `lang`) and an **Expression** referencing a value under `anonymous_session.metadata.*` (for example, `anonymous_session.metadata.language`), then select **Add**.

    4. To edit an existing claim, select the pencil icon next to it. To delete one, select the trash can icon.
  </Tab>

  <Tab title="Management API">
    To configure claims mapping for your API, make a `PATCH` request to the [`/api/v2/resource-servers/{id}`](/docs/api/management/v2/resource-servers/patch-resource-servers-by-id) endpoint:

    ```json theme={null}
    {
      "access_token": {
        "claims_mapping": {
          "custom_claims": [
            {
              "name": "tier",
              "expression": "anonymous_session.metadata.tier"
            },
            {
              "name": "lang",
              "expression": "anonymous_session.metadata.language"
            }
          ]
        }
      }
    }
    ```

    Each entry in `custom_claims` maps a claim `name` on the issued access token to an `expression` that reads a value from the anonymous session, such as `anonymous_session.metadata.<key>`.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      The `PATCH` request replaces the entire `custom_claims` list, so you must include every claim you want to keep. Precede your `PATCH` with a `GET` request to retrieve the existing claims, make the alterations you need, and pass the whole object back in the `PATCH` request.
    </Callout>
  </Tab>
</Tabs>

## Next steps

<Card title="Anonymous Sessions Use Cases" icon="lightbulb" href="/docs/manage-users/sessions/anonymous-sessions/anonymous-sessions-use-cases" horizontal>
  Learn about anonymous sessions use cases.
</Card>