--- title: Session Management API by session identifiers description: The runtime session management application programming interface (API) lets OAuth clients get information about user sessions, extend sessions, revoke sessions, and delete sessions. Knowing the remaining lifetime of a valid session could, for example, let an application prompt the user to extend the session. component: pingfederate version: 12.3 page_id: pingfederate:developers_reference_guide:pf_sess_manage_api_sess_identif canonical_url: https://docs.pingidentity.com/pingfederate/13.1/developers_reference_guide/pf_sess_manage_api_sess_identif.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: September 10, 2026 superseded_by: https://docs.pingidentity.com/pingfederate/13.1/developers_reference_guide/pf_sess_manage_api_sess_identif.html section_ids: session-management-api-by-session-identifiers-endpoints: Session management API by session identifiers endpoints endpoint-pf-wsrestsessionmgmtsessionssri: Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri} sample-get-request: Sample GET request sample-get-responses: Sample GET responses endpoint-pf-wsrestsessionmgmtsessionssriextend: Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri}/extend sample-post-request: Sample POST request sample-response: Sample response endpoint-pf-wsrestsessionmgmtsessionssrirevoke: Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri}/revoke sample-post-request-2: Sample POST request sample-response-2: Sample response endpoint-pf-wsrestsessionmgmtsessionssriauthnsessionsid: Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri}/authnSessions/{id} sample-delete-request: Sample DELETE request return-code: Return code --- # Session Management API by session identifiers The runtime session management application programming interface (API) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)* lets OAuth client *(tooltip: \
\

The application in an OAuth framework that requests access to resources. If the request is approved by the authorization server, the client is issued an access token for the resources.\

\
)*s get information about user sessions, extend sessions, revoke sessions, and delete sessions. Knowing the remaining lifetime of a valid session could, for example, let an application prompt the user to extend the session. An OAuth client can take the pi.sri session identifier from its access token and send it to the session management API in an HTTP GET request. An OAuth client can also send the pi.sri to the session management API in an HTTP POST request to extend or revoke the sessions. The API returns information in JavaScript Object Notation (JSON) *(tooltip: \
\

An open, lightweight data-interchange format that uses human-readable text to store and transmit data.\

\
)* format about each session associated with the `pi.sri`, including: * Last activity time * Idle and maximum timeout time * Authentication source that created the session * Context data * IP address * User agent | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The API response body includes only sessions that were configured with the authentication sessions capability described in [Configuring authentication sessions](../administrators_reference_guide/pf_config_auth_sessions.html). | The session management API works with sessions stored in persistent storage and across clustered nodes. For this API, the runtime APIs audit log only records session revoke events. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If the OAuth client is configured to use any JWT-based authentication method, the Session Management API endpoint won't authenticate using JWTs because the endpoint only supports Client Secret or Client TLS Certificate authentication methods. | To configure PingFederate so that an OAuth client can use the session management API: * Allow the client to access the session management API, as described in [Configuring OAuth clients](../administrators_reference_guide/pf_configuring_oauth_clients.html). * Configure the client's access token manager instance to include a `pi.sri` in access tokens, as described in [Managing session validation settings](../administrators_reference_guide/help_beareraccesstokenmgmtplugintasklet_sessionvalidationstate.html). ## Session management API by session identifiers endpoints The session management API by session identifiers has three endpoints, which all require the `sri` parameter. The OpenID Provider configuration endpoint `/.well-known/openid-configuration` provides configuration information for OAuth clients to access the session management API endpoints. For more information, see [OpenID Provider configuration endpoint](pf_openid_provider_config_endpoint.html). The session management API endpoints return several response codes, including: * `200 OK: The request was successfully processed.` * `400 Bad request: The format of the SRI is invalid.` ## Endpoint `/pf-ws/rest/sessionMgmt/sessions/{sri}` Use HTTP GET requests to get information about all sessions associated with the pi.sri specified by the `sri` parameter. ### Sample GET request ```http GET /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA HTTP/1.1 Host: www.example.com X-XSRF-Header: PingFederate Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI= Cookie: PF=K60mOoBlTvWcD4frFzcKF5 ``` ### Sample GET responses After receiving a successful request, the endpoint returns a response like one of the following samples, depending on whether the status is `HAS_VALID_SESSIONS`, `NO_VALID_SESSIONS`, or `SESSION_REVOKED`: ```json { "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA", "status": "HAS_VALID_SESSIONS", "lastActivityTime": "2020-06-10T17:25:00.461Z", "authnSessions": [ // This section can include multiple sessions { "authnSource": { "sourceType": "IDP_CONN", "id": "L07d8fse7dslShd6d_20HA8jP6", "entityId": "Amazon_Africa_A" // Only for IDP_CONN sourceType sessions }, "id": "ba5a3d97afee5ef9450b710ff932680e3579dc7f", "creationTime": "2020-06-10T17:25:00.454Z", "idleTimeout": "2020-06-10T18:25:00.461Z", "maxTimeout": "2020-06-11T01:25:00.461Z" }, { "authnSource": { "sourceType": "ADAPTER", "id": "HtmlFormAdapter", "adapterType": "HTML Form IdP Adapter" // Only for ADAPTER sourceType sessions }, "id": "7cbef5022be8d841f14a95ace8987cbb34c77a21", "creationTime": "2020-06-10T17:25:00.454Z", "idleTimeout": "2020-06-10T18:25:00.461Z", "maxTimeout": "2020-06-11T01:25:00.461Z" } ], "contextData": { "ipAddress": "127.0.0.1", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" } } ``` ```json { "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA", "status": "NO_VALID_SESSIONS", } ``` ```json { "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA", "status": "SESSION_REVOKED", } ``` ## Endpoint `/pf-ws/rest/sessionMgmt/sessions/{sri}/extend` Use HTTP POST requests to extend the `idleTimeout` value of all sessions associated with the pi.sri specified by the `sri` parameter. ### Sample POST request ```http POST /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA/extend HTTP/1.1 Host: www.example.com X-XSRF-Header: PingFederate Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI= Cookie: PF=K60mOoBlTvWcD4frFzcKF5 ``` ### Sample response ```json { "sri": "Y9tTHRVD7s55Vn2hdrrVxWgRD44..aHbY.tEXnpsf6V1YGT3OWMNWxZjp2m", "status": "HAS_VALID_SESSIONS", "lastActivityTime": "2021-10-14T18:29:00.195Z", "authnSessions": [ { "authnSource": { "sourceType": "ADAPTER", "id": "CIAMHtml", "adapterType": "HTML Form IdP Adapter" }, "id": "8e95ab8600d71a6091af61d54b75ddefb9270c2c", "creationTime": "2021-10-14T18:28:47.205Z", "idleTimeout": "2021-10-14T19:29:00.195Z", "maxTimeout": "2021-10-15T02:28:47.205Z" } ] "contextData": { "ipAddress": "127.0.0.1", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" } } ``` ## Endpoint `/pf-ws/rest/sessionMgmt/sessions/{sri}/revoke` Use HTTP POST requests to revoke all sessions associated with the pi.sri specified by the `sri` parameter. ### Sample POST request ```http POST /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA/revoke HTTP/1.1 Host: www.example.com X-XSRF-Header: PingFederate Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI= Cookie: PF=K60mOoBlTvWcD4frFzcKF5 ``` ### Sample response ```json { "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA", "status": "SESSION_REVOKED", } ``` ## Endpoint `/pf-ws/rest/sessionMgmt/sessions/{sri}/authnSessions/{id}` Use HTTP DELETE requests to remove an authentication session with the specified `id` parameter from the sessions associated with the pi.sri specified by the `sri` parameter. ### Sample DELETE request ```http DELETE /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA/authnSessions/ba5a3d97afee5ef9450b710ff932680e3579dc7f HTTP/1.1 Host: www.example.com X-XSRF-Header: PingFederate Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI= Cookie: PF=K60mOoBlTvWcD4frFzcKF5 ``` ### Return code After receiving a successful request, the endpoint returns an HTTP status of `204 No Content`.