Manage sessions

You can get and terminate user sessions in your space using the REST API.

Note: To enable the session APIs, submit a support ticket.

Get sessions

Space administrators can retrieve session data for their space. This can help you monitor user activity, analyze license usage, and get the IDs of sessions to terminate.

Endpoint

GET .../api/shared_spaces/{space_id}/sessions

Note: Use the ALM-OCTANE-TECH-PREVIEW=true header key.

Request

You can use query parameters to control the data you retrieve.

Note: Sessions must be filtered either by specific session IDs or by their creation date within a 30-day interval.

.../api/shared_spaces/1001/sessions?fields=end_time,user,client_type&query="(end_time=null)"&order_by=start_time

Query examples

To get all open sessions:

.../sessions?query="(end_time=null)"

Returned fields

The following session data fields are available.

Field Name Description
id Unique identifier for the session.
session_identifier A unique identifier specific to the session.
client_type The type of client used for the session (UI, Integration, CI).
user The user associated with the session, with their full name and email address.
client_ip The IP address of the client used for the session.
access_type The type of access used for the session (UI, API).
start_time The timestamp when the session began.
end_time The timestamp when the session ended.
license The type of license associated with the user.

Filtering

You can filter session data using the query parameter. The following criteria are supported:

  • start_time
  • end_time
  • access_type
  • client_ip
  • client_type
  • id
  • license
  • session_identifier
  • user (for user ID)

Grouping

You can group session data using the group_by parameter. The following criteria are supported:

  • access_type
  • client_ip
  • license
  • session_identifier
  • user (for user ID)

Sorting

You can sort session data using the order_by parameter. The following fields are supported:

  • access_type
  • client_ip
  • client_type
  • start_time
  • end_time
  • id
  • license
  • session_identifier

Back to top

Terminate sessions

Space administrators can terminate one or multiple user sessions. This allows administrators to manage active sessions and control access to the tenant.

Endpoint

PUT .../api/shared_spaces/<space_ID>/sessions/terminate/?query="(id='<session_ID>';id='<session_ID>';id='<session_ID>')"

In the query, specify the session IDs that you want to terminate.

Request Body (JSON)

{
   "data": [
     {
       "is_closed": true
     }   
   ]
 }

The API updates the specified sessions by setting the is_closed field to true. When the is_closed field is set, the session end time is automatically updated to the current date and time.

Response

The operation is performed by a background task. To check the status of the background task, you can use the following endpoint, providing the background_task_id returned by the Update Sessions API call.

GET: .../api/shared_spaces/<space_ID>/background_tasks?fields=status,result&query="id=<background_task_ID>"

Permissions and validation

  • Permissions: Only space administrators are authorized to use this API. Site or workspace administrators cannot do this.
  • Validation: The endpoint validates that the target session belongs to the same tenant as the one from which the request is initiated.

Functionality details

  • Bulk and single operations: The API allows terminating one or multiple sessions simultaneously.
  • Partial success: If some session IDs are invalid, the valid ones will still be terminated.

Back to top