--- title: Session Revocation API endpoint description: PingFederate includes a REST-based web service for back-channel session revocation. component: pingfederate version: 13.0 page_id: pingfederate:developers_reference_guide:pf_session_revocation_api_endpoint canonical_url: https://docs.pingidentity.com/pingfederate/13.0/developers_reference_guide/pf_session_revocation_api_endpoint.html revdate: July 2, 2024 section_ids: endpoint-pf-wsrestsessionmgmtrevokedsris: "Endpoint: /pf-ws/rest/sessionMgmt/revokedSris" example: Example logging: Logging related-links: Related links --- # Session Revocation API endpoint PingFederate includes a REST-based web service for back-channel session revocation. This service enables OAuth clients to add sessions to the revocation list or to query their revocation status. This endpoint is not part of the OAuth specification. You must select the **Allow Access to Session Revocation API** checkbox in the configuration for the applicable clients. This endpoint is a URL path extension of the PingFederate runtime endpoint. For example, . | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | OAuth clients must authenticate to the web service using their configured client authentication method. For more information about OAuth client authentication methods, see [Configuring OAuth clients](../administrators_reference_guide/pf_configuring_oauth_clients.html). | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If clients are allowed to add sessions to the revocation list, you can enable the **Check session revocation status** option in the applicable Access Token Management instances for the token validation process to consider whether a session has been added to the revocation list | ## Endpoint:` /pf-ws/rest/sessionMgmt/revokedSris` This resource accepts the POST and GET methods. It also requires the `X-XSRF-HEADER` HTTP header with any value to prevent cross site request forgery. | | | | - | ------------------------------------------------------------------------------------------------- | | | The POST method described in this section requires the element name/value pair formatted in JSON. | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can find information about the Session Revocation API endpoint in the OpenID Provider Configuration endpoint metadata: `ping_revoked_sris_endpoint`. | **POST** A POST request adds a session to the revocation list based on its session identifier, `id`, in the POST data. The ID value corresponds to that of the `pi.sri` element in the ID token. The required `Content-Type` is `application/json`. * Sample request A POST request to add a session with a session identifier of abc123 to the revocation list. ``` POST /pf-ws/rest/sessionMgmt/revokedSris Host: localhost:9031 Authorization: Basic YWNfb2ljX2NsaWVudDphYmMxMjNERUZnaGlqa2xtbm9wNDU2N3JzdHV2d3h5elpZWFdVVDg5MTBTUlFQT25tbGlqaG9hdXRocGxheWdyb3VuZGFwcGxpY2F0aW9u X-XSRF-HEADER: PingFederate Content-Type: application/json {"id":"abc123"} ``` * Return codes | Return code | Description | | ------------------------------ | ------------------------------------------------------------------------------------------ | | `201 – Created` | The session is added to the revocation list | | `400 – Bad Request` | The `X-XSRF-HEADER` HTTP header isn't found in the HTTP POST request | | `401 – Unauthorized` | The response contains details as to why the attempt failed | | `405 - Method Not Allowed` | The request was the wrong type. The revocation endpoint only accepts GET and POST requests | | `415 – Unsupported Media Type` | The `Content-Type: application/json` HTTP header is not found in the HTTP POST request | | `500 – Internal Server Error` | An unknown error has occurred | **GET** A GET request sends a query for the revocation status for a session with its session identifier, `id`, appended to the endpoint. The ID value corresponds to that of `pi.sri` in the ID token. * Sample request A GET request to query the revocation status for a session with a session identifier of abc123. ``` GET /pf-ws/rest/sessionMgmt/revokedSris/abc123 Host: localhost:9031 Authorization: Basic YWNfb2ljX2NsaWVudDphYmMxMjNERUZnaGlqa2xtbm9wNDU2N3JzdHV2d3h5elpZWFdVVDg5MTBTUlFQT25tbGlqaG9hdXRocGxheWdyb3VuZGFwcGxpY2F0aW9u X-XSRF-HEADER: PingFederate ``` If PingFederate authentication sessions are enabled, querying a valid session also extends the session lifetime by the time value specified in the global **Idle Timeout** field or the idle timeout override for the authentication source associated with the session. The latter takes precedence. For externally stored authentication sessions, this operation is optimized to only send updates to the external storage when the remaining idle timeout window is less than 75%. Alternatively, include the optional `updateActivityTime` query parameter and set the value to `false` in the request to query the status of a session without extending its lifetime. ## Example ``` GET /pf-ws/rest/sessionMgmt/revokedSris/abc123?updateActivityTime=false Host: localhost:9031 Authorization: Basic YWNfb2ljX2NsaWVudDphYmMxMjNERUZnaGlqa2xtbm9wNDU2N3JzdHV2d3h5elpZWFdVVDg5MTBTUlFQT25tbGlqaG9hdXRocGxheWdyb3VuZGFwcGxpY2F0aW9u X-XSRF-HEADER: PingFederate ``` * Return codes | Return code | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200 – OK` | `\{"id":"abc123"}` is found in the revocation list | | `400 – Bad Request` | The `X-XSRF-HEADER` HTTP header is not found in the HTTP POST request | | `401 – Unauthorized` | The response contains details as to why the attempt failed | | `404 – Not Found` | `\{"resultId":"session_mgmt_sri_not_revoked","message":"The SRI has not been revoked."}` if the session isn't found in the revocation list.If PingFederate is configured to manage authentication sessions and the request doesn't come with the `updateActivityTime=false` query parameter, the session is extended as well. | | `405 - Method Not Allowed` | The request was the wrong type. The revocation endpoint only accepts GET and POST requests | | `500 – Internal Server Error` | An unknown error has occurred | ## Logging PingFederate records the actions performed through this endpoint in the `runtime-api.log` file. While the events themselves are not configurable, you can adjust the `log4j2.xml` configuration settings to alter the format and desired level of detail surrounding each event. Each log entry contains information relating to the event, including: * Time the event occurred on the PingFederate server * Administrator username performing the action * Authentication method * Client IP * HTTP method * REST endpoint * HTTP status code Each of the above fields is separated by a vertical pipe (`|`) for ease of parsing. ## Related links * [Back-Channel Session Revocation](../administrators_reference_guide/pf_backchannel_sess_revocat.html) * [Sessions](../administrators_reference_guide/pf_sessions.html)