--- title: Manage sessions using REST description: To manage authenticated sessions using REST, send requests to the /json/sessions endpoint, as shown in the following examples. component: pingam version: 8.1 page_id: pingam:am-sessions:managing-sessions-REST canonical_url: https://docs.pingidentity.com/pingam/8.1/am-sessions/managing-sessions-REST.html keywords: ["Sessions", "REST API", "Log Out", "Properties"] page_aliases: ["authentication-guide:action-invalidating-sessions.adoc", "sessions-guide:managing-sessions-REST.adoc"] section_ids: rest-api-session-information: Get information about sessions rest-api-token-validation: Validate sessions rest-api-session-refresh: Refresh server-side sessions invalidate-sessions: Invalidate sessions invalidate-sessions-by-handle: Invalidate specific sessions invalidate-sessions-user: Invalidate all sessions for a user rest-api-session-properties: Get and set session properties --- # Manage sessions using REST To manage authenticated sessions using REST, send requests to the `/json/sessions` endpoint, as shown in the following examples. ## Get information about sessions To get information about an authenticated session, send an HTTP POST request to the `/json/sessions/` endpoint, using the `getSessionInfo` action. This action returns information about the session token provided in the `iPlanetDirectoryPro` header by default. To get information about a different session token, include it in the POST body as the value of the `tokenId` parameter. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To retrieve custom session properties in authentication trees, use a [Scripted Decision node](https://docs.pingidentity.com/auth-node-ref/8.1/scripted-decision.html) for user attributes and session properties or a [Set Session Properties node](https://docs.pingidentity.com/auth-node-ref/8.1/set-session-properties.html) for session properties only. | The following example shows an administrative user passing their session token in the `iPlanetDirectoryPro` header and the session token of `bjensen` as the value of the `tokenId`: ```bash $ curl \ --request POST \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=4.0" \ --header "Content-type: application/json" \ --data '{ "tokenId": "BXCCq…​NX*1*" }' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=getSessionInfo' { "username": "bjensen", "universalId": "id=bjensen,ou=user,dc=am,dc=example,dc=com", "realm": "/", "latestAccessTime": "2024-02-21T14:31:18Z", "maxIdleExpirationTime": "2024-02-21T15:01:18Z", "maxSessionExpirationTime": "2024-02-21T16:29:56Z", "properties": { "AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932" } } ``` The `getSessionInfo` action doesn't refresh the session idle timeout. To obtain session information about a server-side session *and* reset the idle timeout, use the `getSessionInfoAndResetIdleTime` action, as follows: ```bash $ curl \ --request POST \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=4.0, protocol=1.0" \ --header "Content-type: application/json" \ --data '{ "tokenId": "BXCCq…​NX*1*" }' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=getSessionInfoAndResetIdleTime' { "username": "bjensen", "universalId": "id=bjensen,ou=user,dc=am,dc=example,dc=com", "realm": "/", "latestAccessTime": "2020-02-21T14:32:49Z", "maxIdleExpirationTime": "2020-02-21T15:02:49Z", "maxSessionExpirationTime": "2020-02-21T16:29:56Z", "properties": { "AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932" } } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * You can't reset the idle timeout of a client-side session. * The `AMCtxId` property represents the audit ID for the session. To return the `AMCtxId` property in the session query response (as in this example) you must include `AMCtxId` in the Session Properties to return for session queries field under Realms > *realm name* > Services > Session Property Whitelist Service. | ## Validate sessions To check if a session token is valid, send an HTTP POST request to the `/json/sessions/` endpoint with the `validate` action. Provide the session token in the POST data as the value of the `tokenId` parameter. Provide the session token of an *administrative user* in the `iPlanetDirectoryPro` header. | | | | - | --------------------------------------------------------------------------------------------------------- | | | If you don't specify a `tokenId`, this request validates the session in the `iPlanetDirectoryPro` header. | The following example shows an administrative user, such as `amAdmin`, validating a session token for `bjensen`: ```bash $ curl \ --request POST \ --header "Content-type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.0, protocol=1.0" \ --data '{ "tokenId": "BXCCq…​NX*1*" }' \ 'https://am.example.com:8443/am/json/realms/root/sessions?_action=validate' ``` If the session token is valid, the user ID and its realm is returned: ```bash { "valid": true, "sessionUid": "c888fe06-dcb4-43e9-b74a-db838c163aa6-164702", "uid": "bjensen", "realm": "/alpha" } ``` By default, validating an authenticated session resets the session's idle time, which triggers a write operation to the CTS token store. To avoid this, include `refresh=false`, for example, `validate&refresh=false`. ## Refresh server-side sessions To reset the idle time of a server-side authenticated session, send an HTTP POST request to the `/json/sessions/` endpoint, with the `refresh` action. This action refreshes the session token provided in the `iPlanetDirectoryPro` header by default. To refresh a different session token, include it in the POST body as the value of the `tokenId` query parameter. The following example shows an administrative user passing their session token in the `iPlanetDirectoryPro` header, and bjensen's session token as the `tokenId` parameter: ```bash $ curl \ --request POST \ --header 'Content-Type: application/json' \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ --data '{ "tokenId": "BXCCq…​NX*1*" }' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=refresh' { "uid": "bjensen", "realm": "/alpha", "idletime": 0, "maxidletime": 30, "maxsessiontime": 120, "maxtime": 6171 } ``` On success, AM resets the idle time for the server-side session, and returns timeout details of the authenticated session. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * Resetting a server-side session's idle time triggers a write operation to the CTS token store. To avoid the overhead of write operations to the token store, use the `refresh` action *only* if you want to reset a server-side session's idle time. * The idle time of a session is reset subject to the [latest access time update frequency](../setup/services-configuration.html#latest-access-time-update-frequency). AM updates a session's latest access time at most this often. The default is 60 seconds. * AM doesn't monitor idle time for client-side sessions, so you can't use the `tokenId` of a client-side session to refresh the session's idle time. | ## Invalidate sessions To invalidate an authenticated session, send an HTTP POST request to the `/json/sessions/` endpoint with the `logout` action. This action invalidates the session token provided in the `iPlanetDirectoryPro` header by default: ```bash $ curl \ --request POST \ --header "Content-type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/sessions/?_action=logout' { "result": "Successfully logged out" } ``` On success, AM invalidates the authenticated session and returns a success message. If the token isn't valid and can't be invalidated, an error message is returned: ```json { "result": "Token has expired" } ``` An administrative user can invalidate the session of another authenticated user by providing the session token as the value of the `tokenId` query parameter. This example shows an administrative user passing their session token in the `iPlanetDirectoryPro` header and invalidating bjensen's session by passing her session token in the `tokenId` parameter: ```bash $ curl \ --request POST \ --header "Content-type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ --data '{ "tokenId": "BXCCq…​NX*1*" }' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=logout' { "result": "Successfully logged out" } ``` ### Invalidate specific sessions To invalidate specific authenticated sessions for a user, first obtain a list of the user's active sessions. Send an HTTP GET request to the `/json/sessions/` endpoint, using the SSO token of an administrative user, such as `amAdmin` as the value of the `iPlanetDirectoryPro` header. Use a `queryFilter` to specify the name of the user and the realm to search. For example, to obtain the list of active sessions for `bjensen` in the `alpha` realm, the query filter value would be: ``` username eq "bjensen" and realm eq "/alpha" ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The query filter value must be URL-encoded when sent over HTTP.Learn more about query filter parameters in [Query](../am-rest/rest-intro.html#about-crest-query). | In the following example, there are two authenticated sessions. Note the value of the `sessionHandle` properties. ```bash $ curl \ --request GET \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/sessions?_queryFilter=username%20eq%20%22bjensen%22%20and%20realm%20eq%20%22%2Falpha%22' { "result": [ { "username": "bjensen", "universalId": "id=bjensen,ou=user,o=alpha,ou=services,dc=am,dc=example,dc=com", "realm": "/alpha", "sessionHandle": "shandle:ITnOR5S…​AA.", "latestAccessTime": "2022-11-11T09:32:28.265Z", "maxIdleExpirationTime": "2022-11-11T10:02:28Z", "maxSessionExpirationTime": "2022-11-11T11:32:28Z" }, { "username": "bjensen", "universalId": "id=bjensen,ou=user,o=alpha,ou=services,dc=am,dc=example,dc=com", "realm": "/alpha", "sessionHandle": "shandle:JfMui6O…​AA.", "latestAccessTime": "2022-11-11T09:32:24.395Z", "maxIdleExpirationTime": "2022-11-11T10:02:24Z", "maxSessionExpirationTime": "2022-11-11T11:32:24Z" } ], "resultCount": 2, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 } ``` To log out specific sessions, send an HTTP POST request to the `/json/sessions/` endpoint, with the `logoutByHandle` action. Include an array of the session handles to invalidate as values of the `sessionHandles` property in the POST body. Use the SSO token of an administrative user, such as `amAdmin`, as the value of the `iPlanetDirectoryPro` header. This example invalidates the sessions returned by the previous query: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ --data '{ "sessionHandles": [ "shandle:ITnOR5S…​AA.", "shandle:JfMui6O…​AA." ] }' \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/sessions/?_action=logoutByHandle' { "result": { "shandle:ITnOR5S…​AAA.": true, "shandle:JfMui6O…​AA.": true } } ``` ### Invalidate all sessions for a user To invalidate (log out) all authenticated sessions for a user, send an HTTP POST request to the `/json/sessions/` endpoint with the `logoutByUser` action, specifying the username in the request payload. Provide the session token of an *administrative user* in the `iPlanetDirectoryPro` header. Users can invalidate their own sessions by providing their session token in the `iPlanetDirectoryPro` header and their username in the body of the request. This example logs out all bjensen's sessions: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=5.1, protocol=1.0" \ --data '{"username": "bjensen"}' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=logoutByUser' { "result": true } ``` Session invalidation by user works slightly differently for server-side and client-side sessions. * Server-side sessions Logout by user simply deletes all authenticated sessions for that user. This action creates an `AM-SESSION-LOGGED-OUT` event in the activity log and an `AM-LOGOUT` event in the authentication log, as with any other session termination. * Client-side sessions When the user logs out, a *logout token* is created. If there is only one AM instance in the site, the logout token is added to a local cache of that AM instance. If there are multiple AM instances in the site, the other instances poll the CTS a specified interval to update their logout token cache. Learn more in the [Enable Invalidation of Sessions Based on User Identifier](../setup/services-configuration.html#global-session-client-side-logout) property. An `AM-LOGOUT-USER-TOKEN` event is created in the activity log when the user is logged out. The action is `CREATE` or `UPDATE` depending on whether a token for the user being logged out already exists. The `userId` component of this audit entry is that of the caller, not of the target. For example, if an administrative user logs out another user, the `userId` is that of the administrative user, not that of the user being logged out. The `objectId` indicates the target of the operation. A `DELETE` event is audited when the logout token expires and is deleted from the CTS. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | - Logout by user is called on a specific realm. If the same user has existing sessions in multiple realms, you must perform the action in each realm to invalidate *all* sessions for that user. - Logout by user is disabled for client-side sessions by default. To let administrators invalidate all *client-side* sessions for a specific user, set Enable Invalidation of Sessions Based on User Identifier to `true` in the [client-side session properties](../setup/services-configuration.html#global-session-client-based-sessions) before you perform the action. | ## Get and set session properties Use the REST API to read and update properties on authenticated sessions. Define the properties you want to set in the session property allowlist service configuration. Find information on allowlisting session properties in the [Session Property Whitelist service](../setup/services-configuration.html#global-amsessionpropertywhitelist). You can use the REST API to: * Get the names of the properties that you can read or update. This is the same set of properties configured in the Session Property Whitelist service. * Read and update property values. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The ability to set, change and delete session properties is affected by the *session state*:* For server-side sessions, you can manipulate session properties at any time during the session's lifetime. * For client-side sessions, you can manipulate session properties only during the authentication process, before the user receives the session token from AM. For example, you can set or delete properties on a client-side session from within a post-authentication plugin. | Differentiate the user who performs the operation from the session affected by the operation as follows: * Specify the session token of the user performing the operation on session properties in the `iPlanetDirectoryPro` header. * Specify the session token of the user whose session is to be read or modified as the `tokenId` parameter in the body of the REST API call. * Omit the `tokenId` parameter from the body of the REST API call if the session of the user performing the operation is the same session that you want to read or modify. The following examples assume that you configured a property named `LoginLocation` in the Session Property Whitelist service. To retrieve the names and values of the properties you can get or set, send an HTTP POST request to the `json/sessions` endpoint, with the `getSessionProperties` action: ```bash $ curl \ --request POST \ --header "Content-type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ --data '{ "tokenId": "BXCCq…​NX*1*" }' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=getSessionProperties' { "LoginLocation": "" } ``` To set the value of a session property, send an HTTP POST request to the `/json/sessions/` endpoint, with the `updateSessionProperties` action. If you do not specify a `tokenId` parameter in the request body, the operation affects the session specified in the `iPlanetDirectoryPro` header: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ --data '{"LoginLocation":"40.748440, -73.984559"}' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=updateSessionProperties' { "LoginLocation": "40.748440, -73.984559" } ``` To set multiple properties in a single REST API call, specify the list of properties and their values in the JSON payload; for example: ``` --data '{"property1":"value1", "property2":"value2"}' ``` To set the value of a session property on another user's session, specify the session token of the user performing the action in the `iPlanetDirectoryPro` header and the session token to be modified as the value of the `tokenId`: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ --data '{"LoginLocation": "40.748440, -73.984559", "tokenId": "BXCCq…​NX*1*"}' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=updateSessionProperties' { "LoginLocation": "40.748440, -73.984559" } ``` If the user attempting to modify the session doesn't have sufficient access privileges, the preceding examples result in a 403 Forbidden error. You can't set properties internal to AM sessions. If you try to modify an internal property in a REST API call, AM also returns a 403 Forbidden error; for example: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: AQICS…​NzEz*" \ --header "Accept-API-Version: resource=3.1, protocol=1.0" \ --data '{"AuthLevel":"5", "tokenId": "BXCCq…​NX*1*"}' \ 'https://am.example.com:8443/am/json/realms/root/sessions/?_action=updateSessionProperties' { "code": 403, "reason": "Forbidden", "message": "Forbidden" } ``` Find a list of the default session properties in [Session properties](../am-authentication/auth-tree-webhooks.html#session-properties).