--- title: Manage sessions using REST description: To manage sessions using REST, send requests to the /json/sessions endpoint, as shown in the following examples. component: pingam version: 7.2 page_id: pingam:sessions-guide:managing-sessions-REST canonical_url: https://docs.pingidentity.com/pingam/8.1/am-sessions/managing-sessions-REST.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Sessions", "REST API", "Log Out", "Properties"] superseded_by: https://docs.pingidentity.com/pingam/8.1/am-sessions/managing-sessions-REST.html 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 rest-api-session-properties: Get and set session properties --- # Manage sessions using REST To manage sessions using REST, send requests to the `/json/sessions` endpoint, as shown in the following examples. ## Get information about sessions To get information about a 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. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For information on retrieving custom session properties:- If you are using authentication modules, refer to [How do I retrieve user attributes from a session using the REST API?](https://backstage.pingidentity.com/knowledge/kb/article/a72365672) in the *ForgeRock Knowledge Base*. - For authentication trees, use the [Scripted Decision node](../authentication-guide/auth-node-configuration-hints.html#auth-node-scripted-decision) to retrieve user attributes and session properties, or the [Set Session Properties node](../authentication-guide/auth-node-configuration-hints.html#auth-node-set-session-properties) for session properties only. | The following example shows an administrative user passing their session token in the `iPlanetDirectoryPro` header, and the session token of the `demo` user 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://openam.example.com:8443/openam/json/realms/root/sessions/?_action=getSessionInfo' { "username": "demo", "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org", "realm": "/", "latestAccessTime": "2020-02-21T14:31:18Z", "maxIdleExpirationTime": "2020-02-21T15:01:18Z", "maxSessionExpirationTime": "2020-02-21T16:29:56Z", "properties": { "AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932" } } ``` The `getSessionInfo` action does not refresh the session idle timeout. To obtain session information about a server-side session and also reset the idle timeout, use the `getSessionInfoAndResetIdleTime` endpoint, as follows. You cannot reset the idle timeout of client-side sessions. ```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://openam.example.com:8443/openam/json/realms/root/sessions/?_action=getSessionInfoAndResetIdleTime' { "username": "demo", "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org", "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 cannot 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`, under Realms > *Realm Name* > Services > Session Property Whitelist Service. | ## Validate sessions To check over REST whether a session token is valid, perform an HTTP POST to the `/json/sessions/` endpoint using the `validate` action. Provide the session token in the POST data as the value of the `tokenId` parameter. You must also provide the session token of an administrative user in the `iPlanetDirectoryPro` header. If you don't specify the `tokenId` parameter, the session in the `iPlanetDirectoryPro` header is validated instead. The following example shows an administrative user, such as `amAdmin`, validating a session token for the `demo` user: ```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://openam.example.com:8443/openam/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 a session resets the session's idle time, which triggers a write operation to the Core Token Service 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 session using REST, perform an HTTP POST to the `/json/sessions/` endpoint, using the `refresh` action. The endpoint will refresh 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 the session token of the `demo` user 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://openam.example.com:8443/openam/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 session. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * Resetting a server-side session's idle time triggers a write operation to the Core Token Service (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](../reference/global-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 does not monitor idle time for client-side sessions, so you cannot use the `tokenId` of a client-side session to refresh the session's idle time. | ## Invalidate sessions To invalidate a 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://openam.example.com:8443/openam/json/realms/root/realms/alpha/sessions/?_action=logout' { "result": "Successfully logged out" } ``` On success, AM invalidates the session and returns a success message. If the token is not valid and cannot be invalidated an error message is returned: ```json { "result": "Token has expired" } ``` To invalidate a different session token, include it in the POST body as the value of the `tokenId` parameter. For example, the following command shows an administrative user passing their session token in the `iPlanetDirectoryPro` header, and the session token of the `demo` user 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://openam.example.com:8443/openam/json/realms/root/sessions/?_action=logout' { "result": "Successfully logged out" } ``` ## Get and set session properties AM lets you read and update properties on users' sessions using REST API calls. Before you can perform operations on session properties using the REST API, you must first define the properties you want to set in the session property allowlist service configuration. For information on allowlisting session properties, see [Session Property Whitelist service](../reference/global-services-configuration.html#global-amsessionpropertywhitelist). You can use REST API calls for the following purposes: * To retrieve 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. * To read property values. * To update property values. Session state affects the ability to set and delete properties as follows: * You can set and delete properties on a server-side session at any time during the session's lifetime. * You can only set and update properties on a client-side session during the authentication process, before the user receives the session token from AM. For example, you could set or delete properties on a client-side session from within a post-authentication plugin. Differentiate the user who performs the operation on session properties 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 configuration. To retrieve the names of the properties you can get or set, and their values, perform an an HTTP POST to the sessions endpoint, `/json/sessions/`, using 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://openam.example.com:8443/openam/json/realms/root/sessions/?_action=getSessionProperties' { "LoginLocation": "" } ``` To set the value of a session property, perform an HTTP POST to the sessions endpoint, `/json/sessions/`, using the `updateSessionProperties` action. If no `tokenId` parameter is present in the body of the REST API call, the session affected by the operation is 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://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties { "LoginLocation": "40.748440, -73.984559" } ``` You can set multiple properties in a single REST API call by specifying a set of fields and their values in the JSON data. 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 `updateSessionProperties` action in `iPlanetDirectoryPro`, and specify the session token to be modified in the POST body as the value of 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 '{"LoginLocation": "40.748440, -73.984559", "tokenId": "BXCCq…​NX*1*"}' \ 'https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties' { "LoginLocation": "40.748440, -73.984559" } ``` If the user attempting to modify the session does not have sufficient access privileges, the preceding examples result in a 403 Forbidden error. You cannot set properties internal to AM sessions. If you try to modify an internal property in a REST API call, a 403 Forbidden error is returned. 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://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties' { "code": 403, "reason": "Forbidden", "message": "Forbidden" } ``` For a list of the default session properties, refer to [Session properties](../authentication-guide/about-authentication-trees.html#session-properties).