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

Dashboard

1. Navigate to Dashboard > Applications > Applications and select your application.
2. Select the Claims Mapping tab.
3. Add the claims you need and their expressions.
4. Select Save.

Management API

Make a PATCH request to the /api/v2/clients/{client_id} endpoint:

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"
        }
      ]
    }
  }'

Use cases

Include session ID in access token

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

{
  "access_token": {
    "custom_claim_mappings": [
      {
        "name": "anon_session_id",
        "expression": "anonymous_session.session_id"
      }
    ]
  }
}

The resulting access token includes:

{
  "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:

{
  "access_token": {
    "custom_claim_mappings": [
      {
        "name": "country",
        "expression": "anonymous_session.metadata.country"
      },
      {
        "name": "language",
        "expression": "anonymous_session.metadata.language"
      }
    ]
  }
}

The resulting access token includes:

{
  "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:

{
  "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:

{
  "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 — Use Actions to migrate session data at login or sign-up.
• Anonymous Sessions Best Practices — Security and performance recommendations.