Configure Custom Claims for Anonymous Sessions

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

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

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

Manage Users

Manage Access

Configure Custom Claims for Anonymous Sessions

Configuring Claims Mapping

Using the Dashboard

Using the Management API

Next steps

​Configuring Claims Mapping

​Using the Dashboard

​Using the Management API

​Next steps

Configuring Claims Mapping

Using the Dashboard

Using the Management API

Next steps