Skip to main content
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 Session Metadata is not a secure data store and should not be used to store sensitive information. This includes secrets and high-risk PII like social security numbers or credit card numbers, etc. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes. To learn more, read Auth0 General Data Protection Regulation Compliance.

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