Configure Session Metadata

To configure session metadata, you can use an Auth0 Post-Login Action and the Management API. You can also include it in the OpenID Connect Back-Channel Logout token.

You can manage session metadata CRUD (create, replace, update, delete) requests using the Management API:

Make a GET request to the /api/v2/sessions/{id} endpoint:

GET /api/v2/sessions/{id}

Make a PATCH request to the /api/v2/sessions/{id} endpoint:

PATCH /api/v2/sessions/{id}
Content-Type: application/json

{
  "session_metadata": {
    "my_metadata": "my new metadata"
  }
}

Make a PATCH request to the /api/v2/sessions/{id} endpoint:

PATCH /api/v2/sessions/{id}
Content-Type: application/json

{
  "session_metadata": {}
}

You can manage session metadata CRUD operations using the api.session objects with a post-login Action. This allows you to manage session metadata based on user or context-specific logic.

Use the event.session.metadata?.devicename object to read the devicename metadata:

const device = event.session.metadata?.deviceName;

Use the api.session.setMetadata() method to update the session metadata:

api.session.setMetadata("deviceName", "Auth0's iPhone");

Changes are immediately available in the event.session object in subsequent Actions. 

Use the following api.session objects to delete session metadata:

• api.session.deleteMetadata("key") deletes the specified session metadata

• api.session.evictMetadata() deletes all session metadata 

To learn more about these objects, review:

• Event object: Learn about the refresh token Event object and properties.

• API object: Learn about the refresh token API object and methods.

You can configure the logout_token to include session metadata using the Auth0 Dashboard or the Management API. 

To configure OIDC Back-Channel Logout token with session metadata:

1. Navigate to Dashboard > Applications and select your application.

2. Select the Settings tab. 

3. Under OpenID Connect Back-Channel Logout > Back-Channel Logout URL, add the application logout URI that will receive the logout_tokens.

4. Set Back-Channel Logout Initiators to either:

   • Selected initiators only or

   • All supported initiators

5. Toggle on Include Session Metadata.

6. Select Save Changes.

Once configured, the logout_token will include all stored session metadata.

You can use the /api/v2/clients/{id} endpoint to include session metadata in the logout_token.

Make a PATCH request to the /api/v2/sessions/{id} endpoint:

"oidc_backchannel_logout": {
  "backchannel_logout_initiators": {
    "mode": "all"
  },
  "backchannel_logout_urls": [
    "https://httpdump.app/inspect/9bccf574-e55f-4b2e-9822-f37372588fc1"
  ],
  "backchannel_logout_session_metadata": {
    "include": true
  }
}

You can monitor session metadata activity through tenant logs.

You can view log events by navigating to Dashboard > Monitoring > Logs or retrieve logs using the Management API logs endpoint.

• A warning w event code indicates an error occurred during a session metadata operation:

"type" : "w"
"details": {
  "session": {
    "metadata" : {
      "error" : "error executing <function> - <reason>"
    }
  }
}

• A successful s event code contains session metadata information if it has been modified as per the schema below:

"details": {
 "session": {
   "metadata" : {
     "operation": "set" | "delete" | "evict",
     "keys": ["deviceName", "location"],  // omit for evict
     "cleared": true                      // only for evict    
   }
 }

For Management API session metadata activity, you can review the response message:

{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}