Skip to main content
Session Metadata is currently in Early Access for Enterprise customers only. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s product release cycle, read Product Release Stages.
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.

​
Auth0 Management API

You can manage session metadata CRUD (create, replace, update, delete) requests using the Management API:
Calls to the /api/v2/sessions/{id} endpoint require a Management API access token with the update:session scope.

​
Retrieve existing session metadata

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

​
Add or update existing session metadata

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

​
Delete session metadata

Make a PATCH request to the /api/v2/sessions/{id} endpoint: 
PATCH /api/v2/sessions/{id}
Content-Type: application/json

{
  "session_metadata": {}
}

​
Auth0 Post-Login Actions

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.

​
Retrieve existing session metadata

Use the event.session.metadata?.deviceName object to read the deviceName metadata: 
const device = event.session.metadata?.deviceName;
The event.session.metadata object includes metadata set in: *Previous Actions within the same flow *Prior transactions if the session was reused

​
Add or update existing metadata

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.

​
Delete session metadata

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.

​
OIDC Back-Channel Logout

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

​
Auth0 Dashboard

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.

​
Auth0 Management API

You can use the /api/v2/clients/{id} endpoint to update your application 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
  }
}

​
Error handling

You can review Session metadata log events by navigating to Dashboard > Monitoring > Logs or retrieve logs using the Management API logs endpoint.
  • If an error occurs while adding or updating Session metadata with Actions, the authentication transaction fails and an error is returned to the callback URL.
A failure f event code is logged with its correspoding error: 
{
  "error": "access_denied",
  "error_description": "Failed to set session metadata: Invalid metadata: Metadata keys may only include letters, numbers, underscores, or hyphens",
  "state": "my-custom-state"
}
  • If a failure occurs when managing Session metadata using the Auth0 Management API, the API responds with an HTTP status: 400 error and its corresponding message:
{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}