Configure Custom Claims for Anonymous Sessions

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

When your resource servers need additional information about a user but you are only passing along an access token, you can augment the access token with custom claims to store additional data.

A common way to set a custom claim is by calling api.accessToken.setCustomClaim() in a post-login Action. However, in an 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:

{
  "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 or the Management API.

Auth0 Dashboard

1. Navigate to Dashboard > Applications > APIs, and select the API you want to configure the claims for.

2. Select 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.

Management API

To configure claims mapping for your API, make a PATCH request to the /api/v2/resource-servers/{id} endpoint:

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

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.

Next steps

Anonymous Sessions Use Cases

Learn about anonymous sessions use cases.