Skip to main content

Starting a privileged session, and where it appears

The Sessions screen lists and terminates sessions; it does not start one. Today, starting a session is an API call — what it needs, and where the result shows up.

Written for whoever runs IT6 min readUpdated

You open Privileged access → Active Sessions expecting a way to begin one, and the screen only lists sessions that already exist, with a Terminate button next to any that are live and a Play button next to any with a recording. There is no New session or Connect control anywhere on it. That is not a missing button so much as a missing screen: starting a session is not yet a console action at all — it is an API call.

The call that starts one

A session is created with a POST carrying the credential to use and the target to reach — the credential ID, the target host, the target port, the protocol (ssh or rdp), and, if the credential's policy requires one, the ID of an approved access request. If the policy also requires a step-up factor at connection time, an MFA token goes in the same call.

Starting a session, using an API token with the right permission
POST /api/v1/organizations/{orgID}/pam/sessions
{
  "credential_id": "cred_...",
  "target_host": "10.20.0.14",
  "target_port": 22,
  "protocol": "ssh",
  "access_request_id": "areq_..."   // omit if the policy needs none
}

The response is the same shape you would see if a console button existed: a host, a port, an address and an expiry time for the listener Qorionix opened for you. From there, connecting is exactly what Proxied SSH sessions describes.

What has to be true before this call succeeds

  • The credential must already exist in the vault and be attached to a target — see The credential vault and Targets and devices.
  • If a PAM access policy on that credential requires approval, you need an approved, unused access request first — see Access requests and approvals. An approval is single-use: it records the session it started and cannot be reused for a second one.
  • You need the PAM permission the credential's policy calls for, which is not necessarily the same permission that let you view the credential in the first place.

Where it shows up afterwards

Once started, the session appears in Privileged access → Active Sessions immediately, with a live status and a Terminate control while it is open. When it ends, it moves into the same list's history with whatever recording was captured, playable from there — see Session recording and transcripts for exactly what "playable" currently means and where it falls short of a real player.

What to do next

  1. Read Proxied SSH sessions or Proxied RDP sessions fully before your first real session — the connection step is not what you would guess.
  2. If the call is refused, read A privileged session will not start for the specific error shapes.
  3. Read PAM access policies to know in advance whether the credential you plan to use needs an access request first.

Was this article wrong?

If a procedure here does not match what you see, or a limit we described has changed, tell us and we will fix the page. Email us about this article, or see how to get help if you need an answer rather than a correction.

Everything in privileged access