Skip to main content

PSM Session Lifecycle and Administration APIs

This article explains how the Privileged Session Manager (PSM) handles sessions across their lifecycle, from initial credential checkout to final uploading of recorded data. It describes the REST APIs that manage each phase (connecting, polling, ending, encoding, uploading) and highlights how these processes remain reliable even if one component fails.

📚Learn How Session Data Is Processed

If you're new to how the Uploader and Encoder work together, see the PSM Uploader and Encoder Flow article for broader context on how raw session data is processed and stored.

Lifecycle Overview​

A PSM session typically begins when a user checks out credentials and initiates a remote connection, creating a PrivSession record with a status of "Connected." The PSM App periodically calls the Polling API to update the session's LastReported timestamp, ensuring the system knows it's still active. If the session ends—because the user disconnected or the credential's time limit expired—the status becomes "Ended."

An Encoder then looks for ended or idle sessions (where LastReported is out of date). It changes the session to "Encoding," processes raw data (screenshots, clipboard, keystrokes), and eventually marks it as "Done-Encoded." Next, an Uploader claims sessions marked "Done-Encoded," switches them to "Uploading," and transfers the finished files to configured storage (UNC, AWS, or Azure). The session finally moves to "Done-Uploaded."

A permanent workflow in EmpowerID monitors each step. If a component (PSM App, Encoder, Uploader) fails to update a session within a set time, the workflow marks that session as terminated or moves it forward so it's never left in a limbo state.

Key Fields in the PrivSession Table​

  • Stage – Tracks the session's state (e.g., Connected, Ended, Encoding, Done-Encoded, Uploading, Done-Uploaded).
  • LastReported – The last time (UTC) that the owning process updated the session (via Polling or another API).
  • ProcessInstance – Identifies which process currently manages or owns the session (PSM App, Encoder, Uploader).

Session Management and Claims: Core APIs​

UpdateSession​

Endpoint: POST api/services/v1/secureaccessgateway/UpdateSession

Description
Refreshes the session's end time by setting it to the current UTC time.

Request Example

{ "session": "123e4567-e89b-12d3-a456-426614174000" }

Response (200 OK)

{ "Result": "Success" }

Logic

  1. Retrieves the session by GUID.
  2. Sets EndTime = DateTime.UtcNow.
  3. Saves and returns "Success".

EndSession​

Endpoint: POST api/services/v1/secureaccessgateway/EndSession

Description
Immediately ends a session, marking it terminated in the database.

Request Example

{ "session": "123e4567-e89b-12d3-a456-426614174000", "processInstance": "process_instance_id" }

Response

  • 200 OK
{ "Result": "Success" }
  • 400 Bad Request
{ "StatusCode": 400, "Content": "Process instance not supplied" }

Logic

  1. Validates processInstance.
  2. Sets TerminateSession = true, updates EndTime, and records LastReported.
  3. Saves and returns success.

EncoderClaim​

Endpoint: POST api/services/v1/secureaccessgateway/EncoderClaim

Description
Finds a session ready for encoding (typically a session that's ended or gone idle).

Request Example

{ "processInstance": "encoder_instance" }

Response (200 OK)

{ "SessionIds": ["123e4567-e89b-12d3-a456-426614174000"] }

Logic

  1. Checks processInstance.
  2. Locates an eligible session (e.g., in Ended).
  3. Returns the session ID so the encoder can claim it.

UploderClaim​

Endpoint: POST api/services/v1/secureaccessgateway/UploderClaim

Description
Allows the Uploader to claim a session in Done-Encoded so it can be uploaded.

Request Example

{ "processInstance": "uploader_instance" }

Response

{ "SessionIds": ["123e4567-e89b-12d3-a456-426614174000"] }

Logic

  1. Validates processInstance.
  2. Finds a session that's ready for uploading.
  3. Returns the session GUID in SessionIds.

Checkin​

Endpoint: POST api/services/v1/secureaccessgateway/Checkin

Description
Forces a credential check-in, such as when a user logs off or a session must end early.

Request Example

{ "checkOutId": "123" }

Response

{ "Result": "Success", "Message": "Your operation message here." }

Logic

  1. Parses checkOutId.
  2. Locates the checkout record, triggers a workflow to check in.
  3. Returns success/failure.

Polling and Session Heartbeats​

Endpoint: POST api/services/v1/secureaccessgateway/Polling

Description
Enables the PSM App, Encoder, or Uploader to confirm a session's status and update LastReported. This is the main "heartbeat" mechanism.

Request Example

{ "session": "123e4567-e89b-12d3-a456-426614174000", "processInstance": "psm_app_instance" }

Response

{ "Result": "Success" }

Logic

  1. Validates the session and process instance.
  2. Updates LastReported to the current UTC time.
  3. Returns success.

Recording and Clipboard APIs​

SaveClipboard​

Endpoint: POST api/services/v1/secureaccessgateway/saveclipboard

Description
Records clipboard text in a PrivSessionEvent, provided that clipboard capture is enabled.

Request Example

{ "text": "Sample clipboard text", "session": "123e4567-e89b-12d3-a456-426614174000" }

Response

{ "Result": "Success" }

SaveScreenshot​

Endpoint: POST api/services/v1/secureaccessgateway/savescreenshot

Description
Stores a Base64-encoded screenshot to local or cloud storage.

Request Example

{ "image": "data:image/png;base64,...", "session": "123e4567-e89b-12d3-a456-426614174000" }

Response

{ "Result": "Success" }

Logic

  1. Checks if TerminateSession is set; if so, ends early.
  2. Otherwise, decodes and merges the screenshot into the recording.

SaveSessionRecording​

Endpoint: POST api/services/v1/secureaccessgateway/savesessionrecording

Description
Appends or creates a file for the raw session recording data in the configured storage destination.

Request Example

{ "recording": "SGVsbG8gd29ybGQ=", "session": "123e4567-e89b-12d3-a456-426614174000" }

Response

{ "Result": "Success" }

SaveKeyStrokes​

Purpose
Logs keystrokes for a session if PSMRecordKeyStrokes is enabled, similar to how clipboard events are recorded.

Additional Utility Endpoints​

  • GetUserPlatform – Analyzes the HTTP User-Agent to identify the client's OS.
  • GetIP – Determines the client IP address, checking proxy headers first.
  • GetRemainingMinutesForCheckout – Returns how much time remains for a credential checkout.
  • GetCredential – Retrieves the necessary details (username/password) if the session is valid and the credential is still checked out.

Settings and Status​

GetPAMSettings​

Endpoint: GET api/services/v1/secureaccessgateway/GetPAMSettings

Description
Returns key configuration settings (e.g., PSMStorageMode, PSMEncodingEnabled, PSMEncryptionKey).

Response

{ "PSMStorageMode": "UNC", "PSMEncodingEnabled": true, "PSMEncryptionKey": null }

GetRecordingProcessStatus​

Endpoint: POST api/services/v1/secureaccessgateway/GetRecordingProcessStatus

Description
Retrieves the current recording status (e.g., Encoding, Done-Encoded) for each requested session ID.

Request Example

{ "privSessionIds": [ "123e4567-e89b-12d3-a456-426614174000" ] }

Response

[ { "PrivSessionID": "123e4567-e89b-12d3-a456-426614174000", "RecordingStatus": "Encoding" } ]

UpdateRecordingProcessStatus​

Endpoint: PUT api/services/v1/secureaccessgateway/UpdateRecordingProcessStatus

Description
Updates the session's status (Encoding, Uploading, etc.) and optional fields (e.g., SSH logs, recording format).

Request Example

{ "privSessionId": "123e4567-e89b-12d3-a456-426614174000", "processInstance": "Uploader_01", "recordingStatus": "Uploading", "sshLogsUploaded": true, "recordingFormat": ".mp4" }

Response

{ "Result": "Success" }

JoinSession​

Endpoint: POST api/services/v1/secureaccessgateway/JoinSession

Description
Allows a user or process to connect to a live session, specifying parameters like gateway address and screen resolution.

Request Example

{ "PrivSessionID": "123e4567-e89b-12d3-a456-426614174000", "GatewayServerAddress": "gateway.example.com", "Width": "1024", "Height": "768", "Dpi": "96" }

Response
Returns a string with connection details if successful.

Administration Best Practices​

Regular polling and accurate stage updates are critical for ensuring the Permanent Workflow knows each component's status. Consider the following:

  • Polling Intervals – Configure the PSM App, Encoder, and Uploader to call the Polling endpoint at a steady cadence (e.g., every few minutes).
  • Stage Updates – Always transition the Stage field appropriately (e.g., Encoding to Done-Encoded, Uploading to Done-Uploaded).
  • Storage Setup – Double-check credentials and paths if storing data in AWS or Azure. Errors can lead to partial recordings or upload failures.
  • Time Thresholds—The workflow times out sessions if LastReported is stale. Adjust these thresholds according to operational needs.
  • Forced Check-in – Use the Checkin API or rely on the workflow to reclaim credentials when a session ends or expires.