> Markdown version of https://authpi.com/docs/reference/idp-api/session-management/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Session Management — AuthPI Identity Provider API

Session management endpoints for monitoring and controlling user sessions. Supports OpenID Connect Session Management for single sign-out and session state checking.

## GET /{issuer_id}/check-session.html

**Session Check Iframe**

Serves the HTML page for OpenID Connect Session Management (OIDC Session Management 1.0).

This endpoint returns an HTML page containing JavaScript that listens for postMessage events from the Relying Party (RP) to check if the user's session is still valid.

## How It Works

1. The RP embeds this page in a hidden iframe
2. The RP sends postMessage with `client_id` and `session_state`
3. The iframe validates the session state against the OP's browser state
4. The iframe responds with `unchanged`, `changed`, or `error`

If the session state has changed, the RP should re-authenticate the user or refresh tokens.

**Specification**: [OpenID Connect Session Management 1.0](https://openid.net/specs/openid-connect-session-1_0.html)

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `issuer_id` | string | Required | The unique identifier for the issuer/tenant |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | HTML page with session checking JavaScript | `object` |

## POST /{issuer_id}/check-session

**Validate Session State**

Validates a session state value against the current session (OIDC Session Management 1.0).

This endpoint is called by the check-session iframe to validate the session state. It computes the expected session state based on the current session cookie and compares it with the provided value.

## Origin Validation

The request origin must match one of the client's registered redirect URIs. This prevents malicious sites from checking session validity.

## Response

- `valid: true` - Session state matches, session is unchanged
- `valid: false` - Session state differs or session is invalid

**Note:** This endpoint should not be called directly by applications. Use the check-session iframe instead.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `issuer_id` | string | Required | The unique identifier for the issuer/tenant |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Required | The client ID that received the original session_state |
| `session_state` | string | Required | The session_state value from the authorization response |
| `origin` | string | Required | The origin of the requesting page (must match a registered redirect URI) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Session state validation result | `object` |
| 400 | **Bad Request** - The request is malformed or missing required parameters. | `OAuthError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `OAuthError` |
| 403 | **Forbidden** - The authenticated client or user lacks permission for this operation. | `OAuthError` |
| 404 | **Not Found** - The requested resource does not exist. | `OAuthError` |
| 422 | **Unprocessable Entity** - The request syntax is correct but the data cannot be processed. | `OAuthError` |
| 429 | **Too Many Requests** - Rate limit exceeded. | `OAuthError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `OAuthError` |

## GET /{issuer_id}/session

**Get Session Information**

Retrieves information about the current user's session.

This endpoint returns session metadata including authentication details, device information, and session status. Use this to:

- Display session information in user account settings
- Check when the user last authenticated
- Monitor session status and activity

## Authorization

Requires a valid access token with:
- `sid` (session ID) claim present
- Token audience (`aud`) matching the session's client ID

The token's audience is verified against the session's client to prevent cross-client session access.

## Response

Returns session metadata excluding sensitive fields like tokens and internal identifiers.

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | **Session Information** - Metadata about the user's current session. | `SessionResponse` |
| 400 | **Bad Request** - The request is malformed or missing required parameters. | `OAuthError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `OAuthError` |
| 403 | **Forbidden** - The authenticated client or user lacks permission for this operation. | `OAuthError` |
| 404 | **Not Found** - The requested resource does not exist. | `OAuthError` |
| 422 | **Unprocessable Entity** - The request syntax is correct but the data cannot be processed. | `OAuthError` |
| 429 | **Too Many Requests** - Rate limit exceeded. | `OAuthError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `OAuthError` |

## POST /{issuer_id}/session

**Get Session Information**

Retrieves information about the current user's session.

This endpoint returns session metadata including authentication details, device information, and session status. Use this to:

- Display session information in user account settings
- Check when the user last authenticated
- Monitor session status and activity

## Authorization

Requires a valid access token with:
- `sid` (session ID) claim present
- Token audience (`aud`) matching the session's client ID

The token's audience is verified against the session's client to prevent cross-client session access.

## Response

Returns session metadata excluding sensitive fields like tokens and internal identifiers.

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | **Session Information** - Metadata about the user's current session. | `SessionResponse` |
| 400 | **Bad Request** - The request is malformed or missing required parameters. | `OAuthError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `OAuthError` |
| 403 | **Forbidden** - The authenticated client or user lacks permission for this operation. | `OAuthError` |
| 404 | **Not Found** - The requested resource does not exist. | `OAuthError` |
| 422 | **Unprocessable Entity** - The request syntax is correct but the data cannot be processed. | `OAuthError` |
| 429 | **Too Many Requests** - Rate limit exceeded. | `OAuthError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `OAuthError` |