> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.generaltranslation.app/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to configure Auth0 session metadata

# Configure Session Metadata

<Warning>
  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](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

To configure session metadata, you can use an Auth0 [Post-Login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) and the [Management API](https://auth0.com/docs/api/management/v2). You can also include it in the [OpenID Connect Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout) token.

## Auth0 Management API

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

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Calls to the `/api/v2/sessions/{id}` endpoint require a [Management API access token](/docs/secure/tokens/access-tokens) with the `update:session` scope.
</Callout>

### Retrieve existing session metadata

Make a `GET` request to the [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/get-session) endpoint:

```bash lines theme={null}
GET /api/v2/sessions/{id}
```

### Add or update existing session metadata

Make a `PATCH` request to the [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint:

```bash lines theme={null}
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}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint:

```bash lines theme={null}
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](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger). 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:

```javascript lines theme={null}
const device = event.session.metadata?.deviceName;
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The `event.session.metadata` object includes metadata set in:
  \*Previous Actions within the same flow
  \*Prior transactions if the session was reused
</Callout>

### Add or update existing metadata

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

```javascript lines theme={null}
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](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Learn about the refresh token Event object and properties.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-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](/docs/get-started/auth0-overview/dashboard) or the [Management API](https://auth0.com/docs/api/management/v2).

### Auth0 Dashboard

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

1. Navigate to [Dashboard > Applications](https://manage.auth0.com/#/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}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint to update your application to include session metadata in the `logout_token`.

Make a `PATCH` request to the [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint:

```json lines theme={null}
"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](https://manage.auth0.com/#/logs) or retrieve logs using the [Management API logs](/docs/api/management/v2/logs/get-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:

```json lines theme={null}
{
  "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:

```json lines theme={null}
{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}
```