Manage sessions over REST

To manage sessions using the REST API, send requests to the /json/sessions endpoint.

The following examples assume you’ve used a service account to obtain an access token with the fr:am:* scope.

The examples also assume you’ve retrieved the session token for the session you’re managing.

Get information about sessions

To get information about a specific session:

Send an HTTP POST request to the /json/sessions/ endpoint, with the getSessionInfo action.
Provide the session token in the POST data as the value of the tokenId.

$ curl \
--request POST \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=4.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": " session-token " }' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=getSessionInfo'
{
  "username": "b0f30dfb-4e01-457e-a567-c258a74e4fe2",
  "universalId": "id=b0f30dfb-4e01-457e-a567-c258a74e4fe2,ou=user,o=alpha,ou=services,ou=am-config",
  "realm": "/alpha",
  "latestAccessTime": "2024-01-12T13:49:25Z",
  "maxIdleExpirationTime": "2024-01-12T14:19:25Z",
  "maxSessionExpirationTime": "2024-01-12T15:49:24Z",
  "properties": {
    "AMCtxId": "b9275f8c-fa83-4455-bdac-d27e8d538a8f-215815",
    "AuthType": ""
  }
}

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:

$ curl \
--request POST \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": " session-token " }' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=getSessionInfoAndResetIdleTime'
{
  "username": "b0f30dfb-4e01-457e-a567-c258a74e4fe2",
  "universalId": "id=b0f30dfb-4e01-457e-a567-c258a74e4fe2,ou=user,o=alpha,ou=services,ou=am-config",
  "realm": "/alpha",
  "latestAccessTime": "2024-01-12T14:18:24Z",
  "maxIdleExpirationTime": "2024-01-12T14:48:24Z",
  "maxSessionExpirationTime": "2024-01-12T15:49:23Z",
  "properties": {
    "AMCtxId": "b9275f8c-fa83-4455-bdac-d27e8d538a8f-215815",
    "AuthType": ""
  }
}

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) include AMCtxId in the Session Properties to return for session queries. Under Native Consoles > Access Management, go to 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.

$ curl \
--request POST \
--header "Content-type: application/json" \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--data '{ "tokenId": " session-token" }' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=validate'

If the session token is valid, PingOne Advanced Identity Cloud returns the user ID and realm:

{
  "valid": true,
  "sessionUid": "b9275f8c-fa83-4455-bdac-d27e8d538a8f-245866",
  "uid": "b0f30dfb-4e01-457e-a567-c258a74e4fe2",
  "realm": "/alpha"
}

By default, validating a session resets the session’s idle time, which triggers a write operation to the Core Token Service (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 session, send an HTTP POST request to the /json/sessions/ endpoint, with the refresh action. Include the session token in the POST body as the value of the tokenId.

$ curl \
--request POST \
--header "Content-type: application/json" \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--data '{ "tokenId": " session-token " }' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=refresh'
{
  "uid": "b0f30dfb-4e01-457e-a567-c258a74e4fe2",
  "realm": "/alpha",
  "idletime": 0,
  "maxidletime": 30,
  "maxsessiontime": 120,
  "maxtime": 6826
}

On success, PingOne Advanced Identity Cloud 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 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. PingOne Advanced Identity Cloud updates a session’s latest access time at most this often. The default is 60 seconds.
PingOne Advanced Identity Cloud 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 a session, send an HTTP POST request to the /json/sessions/ endpoint with the logout action. Include the session token in the POST body as the value of the tokenId.

$ curl \
--request POST \
--header "Content-type: application/json" \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--data '{ "tokenId": "session-token" }' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logout'
{
    "result": "Successfully logged out"
}

If the token isn’t valid (and therefore can’t be invalidated), PingOne Advanced Identity Cloud returns the following error:

{
  "result": "Token has expired"
}

Invalidate specific sessions

To invalidate specific sessions for a user, first obtain a list of the user’s active sessions. Send an HTTP GET request to the /json/sessions/ endpoint with a queryFilter to specify the UUID of the user and the realm to search.

For example, to obtain the list of active sessions for bjensen (whose UUID is b0f30dfb-4e01-457e-a567-c258a74e4fe2) in the alpha realm, the query filter value would be:

username eq "b0f30dfb-4e01-457e-a567-c258a74e4fe2" and realm eq "/alpha"

The query filter value must be URL-encoded when sent over HTTP.

For more information about query filter parameters, refer to Query.

In the following example, bjensen has two active sessions. Note the value of the sessionHandle properties.

$ curl \
--request GET \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions?_queryFilter=username%20eq%20%22b0f30dfb-4e01-457e-a567-c258a74e4fe2%22%20and%20realm%20eq%20%22%2Falpha%22'
{
  "result": [
    {
      "_rev": "647523949",
      "username": "b0f30dfb-4e01-457e-a567-c258a74e4fe2",
      "universalId": "id=b0f30dfb-4e01-457e-a567-c258a74e4fe2,ou=user,o=alpha,ou=services,ou=am-config",
      "realm": "/alpha",
      "sessionHandle": "shandle:flz3sdj5Ts…",
      "latestAccessTime": "2024-01-15T07:42:42.544Z",
      "maxIdleExpirationTime": "2024-01-15T08:12:42Z",
      "maxSessionExpirationTime": "2024-01-15T09:31:22Z"
    },
    {
      "_rev": "1074537861",
      "username": "b0f30dfb-4e01-457e-a567-c258a74e4fe2",
      "universalId": "id=b0f30dfb-4e01-457e-a567-c258a74e4fe2,ou=user,o=alpha,ou=services,ou=am-config",
      "realm": "/alpha",
      "sessionHandle": "shandle:SZtTnGMwnG…",
      "latestAccessTime": "2024-01-15T07:44:00.670Z",
      "maxIdleExpirationTime": "2024-01-15T08:14:00Z",
      "maxSessionExpirationTime": "2024-01-15T09:44:00Z"
    }
  ],
  …
}

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.

This example invalidates the sessions returned by the previous query:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--data '{
    "sessionHandles": [
        "shandle:flz3sdj5Ts…",
        "shandle:SZtTnGMwnG…"
    ]
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logoutByHandle'
{
    "result": {
        "shandle:flz3sdj5Ts…": true,
        "shandle:SZtTnGMwnG…": true
    }
}

Invalidate all sessions for a user

To invalidate (log out) all sessions for a user, send an HTTP POST request to the /json/sessions/ endpoint with the logoutByUser action, specifying the UUID of the user in the request payload.

This example logs out all sessions for user bjensen (whose UUID is b0f30dfb-4e01-457e-a567-c258a74e4fe2):

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=5.1, protocol=1.0" \
--data '{"username": "b0f30dfb-4e01-457e-a567-c258a74e4fe2"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logoutByUser'
{
  "result": true
}

Get and set session properties

Use the REST API to read and update properties on users' sessions. Define the properties you want to get and set in the Session Property Whitelist Service configuration.

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 PingOne Advanced Identity Cloud. 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:

Use an access token for the service account authorized to access these endpoints.
Specify the session token of the user whose session you want to read or modify as the tokenId parameter in the body of the REST API call.

The following examples assume 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:

$ curl \
--request POST \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": " "session-token" " }' \
'https://<tenant-env-fqdn>/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:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": " "session-token" ", "LoginLocation":"40.748440, -73.984559"}' \
'https://<tenant-env-fqdn>/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"}'

If the service account you’re using to modify the session doesn’t have sufficient access privileges, PingOne Advanced Identity Cloud returns a 403 Forbidden error.

You can’t set properties internal to PingOne Advanced Identity Cloud sessions. If you try to modify an internal property in a REST API call, PingOne Advanced Identity Cloud also returns a 403 Forbidden error; for example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer access-token' \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"AuthLevel":"5", "tokenId": " "session-token" "}' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=updateSessionProperties'
{
    "code": 403,
    "reason": "Forbidden",
    "message": "Forbidden"
}

For a list of the default session properties, refer to Session properties.