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

# Configure Custom Claims for Anonymous Sessions

> Learn how to 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="beta" terms="true" contact="Auth0 Support" />

Sometimes your resource servers need additional information passed to them, but an access token is the only thing you're passing along. Auth0 lets you enrich access tokens with [custom claims](/docs/secure/tokens/json-web-tokens/create-custom-claims) whenever your resource server needs more information about the user interacting with it, typically by calling `api.accessToken.setCustomClaim()` in a `post-login` Action.

In an [anonymous sessions](/docs/manage-users/sessions/anonymous-sessions) context, there is no login, and therefore no `post-login` Action execution — which 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**: 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 mints, and include it as a custom claim called `lang`.

## Configuring Claims Mapping

### Using the Dashboard

1. Go to **Applications > APIs**, and select the API you want to configure the claims for.
2. Navigate to the **Claim Mapping** tab.
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.

### Using the 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="triangle-exclamation" color="#F59E0B" 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>

## Next steps

* [Anonymous Sessions Use Cases](/docs/manage-users/sessions/anonymous-sessions/anonymous-sessions-use-cases) Learn about anonymous sessions use cases.