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

> Learn how to configure Auth0 session metadata

# Configure Session Metadata

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.

<Warning>
  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](/docs/secure/data-privacy-and-compliance/gdpr).
</Warning>

## 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."
}
```