IdP API Reference

Session Management — IdP API

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

Base URL: https://idp.authpi.com — see the IdP API overview for the supported flows, or try these endpoints in the interactive reference.

`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

The RP embeds this page in a hidden iframe
The RP sends postMessage with client_id and session_state
The iframe validates the session state against the OP's browser state
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

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`