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

# Anonymous Sessions Claims Mapping

> Include anonymous session attributes in access tokens without writing Actions code using declarative claims mapping.

Claims Mapping lets you include custom data from anonymous sessions in your access tokens without writing Actions code. Using a declarative JSON configuration, you define which anonymous session attributes appear as claims in the access tokens your application receives.

* **No code required** — configure claims through the Auth0 Dashboard or the Management API
* **All session attributes available** — map anything in the session (metadata, session ID, and so on) to a claim in the access token

## How it works

Define claim mappings on an application using the `custom_claim_mappings` array in the `access_token` configuration. Each mapping has:

* `name` — the claim name that appears in the access token
* `expression` — a dot-notation path into the anonymous session object (for example, `anonymous_session.metadata.country`)

When Auth0 issues an access token for an anonymous session, it evaluates each expression and includes matching claims. If an expression returns `null` or `undefined`, the claim is omitted.

## Configure claims mapping

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to [**Dashboard > Applications > Applications**](https://manage.auth0.com/#/applications) and select your application.
    2. Select the **Claims Mapping** tab.
    3. Add the claims you need and their expressions.
    4. Select **Save**.
  </Tab>

  <Tab title="Management API">
    Make a `PATCH` request to the [`/api/v2/clients/{client_id}`](/docs/api/management/v2/clients/patch-clients-by-id) endpoint:

    ```shell wrap lines theme={null}
    curl --request PATCH \
      --url 'https://YOUR_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
      --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{
        "access_token": {
          "custom_claim_mappings": [
            {
              "name": "country",
              "expression": "anonymous_session.metadata.country"
            },
            {
              "name": "language",
              "expression": "anonymous_session.metadata.language"
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

## Use cases

### Include session ID in access token

Include `session_id` so resource servers can trace requests back to a specific anonymous interaction:

```json wrap lines theme={null}
{
  "access_token": {
    "custom_claim_mappings": [
      {
        "name": "anon_session_id",
        "expression": "anonymous_session.session_id"
      }
    ]
  }
}
```

The resulting access token includes:

```json wrap lines theme={null}
{
  "sub": "32adf091-e7aa-4c6e-acbd-55e8cad4f66f",
  "aud": "urn:your:requested:audience",
  "iss": "https://auth.customdomain.com",
  "anon_session_id": "sess_12345",
  "https://auth.customdomain.com/user_type": "anonymous"
}
```

### Include personalization data

Map locale and country data so resource servers can adapt responses without additional API calls:

```json wrap lines theme={null}
{
  "access_token": {
    "custom_claim_mappings": [
      {
        "name": "country",
        "expression": "anonymous_session.metadata.country"
      },
      {
        "name": "language",
        "expression": "anonymous_session.metadata.language"
      }
    ]
  }
}
```

The resulting access token includes:

```json wrap lines theme={null}
{
  "sub": "32adf091-e7aa-4c6e-acbd-55e8cad4f66f",
  "country": "Spain",
  "language": "es-ES",
  "https://auth.customdomain.com/user_type": "anonymous"
}
```

### Guest checkout data

Include cart reference and session ID for e-commerce APIs:

```json wrap lines theme={null}
{
  "access_token": {
    "custom_claim_mappings": [
      {
        "name": "anon_session_id",
        "expression": "anonymous_session.session_id"
      },
      {
        "name": "cart_id",
        "expression": "anonymous_session.metadata.cart_id"
      }
    ]
  }
}
```

The resulting access token includes:

```json wrap lines theme={null}
{
  "sub": "32adf091-e7aa-4c6e-acbd-55e8cad4f66f",
  "anon_session_id": "sess_12345",
  "cart_id": "cart:0987654321",
  "https://auth.customdomain.com/user_type": "anonymous"
}
```

## Limitations

* Maximum 10 custom claims per application.
* Reserved JWT claims cannot be used as claim names: `iss`, `sub`, `aud`, `exp`, and so on.
* Claim names must be unique within a configuration.
* Only direct mapping is available — expressions cannot contain logic or transformations.

## Learn more

* [Transfer Anonymous Sessions to Users](/docs/manage-users/sessions/anonymous-sessions/transfer-to-users) — Use Actions to migrate session data at login or sign-up.
* [Anonymous Sessions Best Practices](/docs/manage-users/sessions/anonymous-sessions/best-practices) — Security and performance recommendations.