Sessions

Quick navigation

GET Sessions

Purpose

Returns a list of sessions.

The maximum number of sessions returned is 100,000.

Required permissions

A member of the Administrators group, or ISA or auditor role to at least one asset Smart Rule.

Query parameters (optional)

  • status: Session status - A single value or comma-delimited list of values:
    • 0: Not Started
    • 1: In Progress
    • 2: Completed
    • 5: Locked
    • 7: Terminated (deprecated)
    • 8: Logged Off
    • 9: Disconnected (RDP only)
  • userID: ID of the user that requested the session

Request body

None.

Response body

Content-Type: application/json

[
    {
        SessionID : int, 
        UserID : int,
        NodeID : string, 
        Status : int,
        ArchiveStatus : int, 
        Protocol : int, 
        StartTime : date, 
        EndTime : date, 
        Duration : int, 
        AssetName : string,
        ManagedSystemID : int, // can be null
        ManagedAccountID : int, 
        ManagedAccountName : string, 
        RecordKey : string,
        Token : string
    },
    …
]

Response body details

  • SessionID: ID of the Session.
  • UserID: ID of the user that requested the session.
  • NodeID: ID of the Session Node.
  • Status: Session status
    • 0: Not Started
    • 1: In Progress
    • 2: Completed
    • 5: Locked
    • 7: Terminated (deprecated)
    • 8: Logged Off
    • 9: Disconnected (RDP only)
  • ArchiveStatus: Session archive status (applicable only when Session Archiving is enabled and configured)
    • 0: Not Archived
    • 1: Archived
    • 2: Restoring (from Archive Repository)
    • 3: Archiving (from Node)
    • 4: Session Not Found (in Archive Repository)
    • 5: Archive Repository Offline/Inaccessible
    • 6: Unknown
  • Protocol: Session protocol
    • 0: RDP
    • 1: SSH
  • StartTime: Start date/time of the session.
  • EndTime: End date/time of the session.
  • Duration: Session duration (seconds).
  • AssetName: Name of the target Managed System.
  • ManagedSystemID: ID of the target Managed System.
  • ManagedAccountID: ID of the target Managed Account.
  • ManagedAccountName: Name of the target Managed Account.
  • RecordKey: The Record Key used for Session replay.
  • Token: The Token used for Session replay.

Response codes

200 – Request successful. Sessions in the response body.

For more information, please see Common response codes.

GET Sessions/{id}

Purpose

Returns a session by ID.

Required permissions

A member of the Administrators group, or ISA or auditor role to at least one asset Smart Rule.

URL parameters

id: ID of the session.

Request body

None.

Response body

Content-Type: application/json

{
    SessionID : int, 
    UserID : int,
    NodeID : string, 
    Status : int,
    ArchiveStatus : int, 
    Protocol : int, 
    StartTime : date, 
    EndTime : date, 
    Duration : int, 
    AssetName : string,
    ManagedSystemID : int,
    ManagedAccountID : int, 
    ManagedAccountName : string, 
    RecordKey : string,
    Token : string
}

Response body details

  • SessionID: ID of the Session.
  • UserID: ID of the user that requested the session.
  • NodeID: ID of the Session Node.
  • Status: Session status
    • 0: Not Started
    • 1: In Progress
    • 2: Completed
    • 5: Locked
    • 7: Terminated (deprecated)
    • 8: Logged Off
    • 9: Disconnected (RDP only)
  • ArchiveStatus: Session archive status (applicable only when Session Archiving is enabled and configured)
    • 0: Not Archived
    • 1: Archived
    • 2: Restoring (from Archive Repository)
    • 3: Archiving (from Node)
    • 4: Session Not Found (in Archive Repository)
    • 5: Archive Repository Offline/Inaccessible
    • 6: Unknown
  • Protocol: Session protocol
    • 0: RDP
    • 1: SSH
  • StartTime: Start date/time of the session.
  • EndTime: End date/time of the session.
  • Duration: Session duration (seconds).
  • AssetName: Name of the target Managed System.
  • ManagedSystemID: ID of the target Managed System.
  • ManagedAccountID: ID of the target Managed Account.
  • ManagedAccountName: Name of the target Managed Account.
  • RecordKey: The Record Key used for Session replay.
  • Token: The Token used for Session replay.

Response codes

200 – Request successful. Sessions in the response body.

For more information, please see Common response codes.

POST Requests/{requestID}/Sessions

Purpose

Create a new session for the given release.

Requirements

Must be the owner of the request ID.

URL parameters

requestID: ID of the request for which to create a session.

Request body

Content- Type: application/json

{
    SessionType : string,
    NodeID : string
}

Request body details

  • SessionType: (required) The type of session to create (SSH or sshticket, RDP or rdpticket, rdpfile, app, or appfile).
  • NodeID: (optional) ID of the node that should be used to establish the session. If NodeID is not given or if the Remote Session Proxy feature is disabled, uses the local node.

Response body (SSH or sshticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    TicketAtHost : string, 
    Link : string, 
    Command : string,
    SessionID : int,
    NodeID : string
}

Response body (RDP or rdpticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    SessionID : int,
    NodeID : string
}

Response body (rdpfile)

RDP File as an attachment.

Response body (app – when the target system is Unix- or ssh-based)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    TicketAtHost : string, 
    Link : string, 
    Command : string,
    SessionID : int,
    NodeID : string
}

Response body (app – when the target system is Windows- or rdp-based)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    SessionID : int,
    NodeID : string
}

Response body (appfile)

RDP File as an attachment.

Response body details

  • ID: The Session Token (same as Ticket).
  • Ticket: The Session Token (same as ID).
  • Host: The target Host Name.
  • Port: The target Host Port.
  • TicketAtHost: Formatted value: {Ticket}@{Host}
  • Link: Formatted ssh link - ssh://{Ticket}@{Host}:{Port}
  • Command: Formatted ssh command: ssh -p {Port} {Ticket}@{Host}
  • SessionID: ID of the Session.
  • NodeID: ID of the Session Node.

Response codes

  • 201– Request successful. Session details or RDP file in the response body.
  • 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
  • 4034 – Request is not yet approved.

For more information, please see Common response codes.

POST Sessions/Admin

Purpose

Create a new admin session.

Required roles

Password Safe Admin Session (Read/Write).

Request body

Content-Type: application/json

{
    SessionType : string, 
    HostName : string, 
    Port : int, // can be null 
    DomainName : string, 
    UserName : string, 
    Password : string, 
    Reason : string, 
    Resolution : string, 
    RDPAdminSwitch : bool, 
    SmartSizing : bool, 
    NodeID : string,
    Record : bool
}

Request body details

  • SessionType: (required) The type of session to create (SSH or sshticket, RDP or rdpticket, or rdpfile)
  • HostName: (required) Name or IP of the target host. Max string length is 128.
  • Port: (optional, default: <configured default port>) Port to use for the connection.
  • DomainName: (optional) The domain name of the user. Max string length is 50.
  • UserName: (required) The username. Max string length is 200.
  • Password: (required) The password.
  • Reason: (optional) The reason for the session.
  • Resolution (RDP-only): (optional, default: <configured default resolution>) The default resolution (i.e 1024x768 or Maximized). Max string length is 50.
  • RDPAdminSwitch (RDP-only): (optional, default: false) True to use the RDP /admin switch, otherwise false.
  • SmartSizing (RDP-only): (optional, default: false) True to use RDP Smart Sizing, otherwise false. Applies only when SessionType=rdpfile.
  • NodeID: (optional) ID of the node that should be used to establish the Session. If NodeID is not given or if the Remote Session Proxy feature is disabled, uses the local node.
  • Record: (optional, default: true) True to record the Session, otherwise false. Ignored and always recorded if the Global Setting Hide Record Checkbox for Admin Sessions is enabled.

Response body (SSH or sshticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string, 
    TicketAtHost : string, 
    Link : string, 
    Command : string, 
    SessionID : int, 
    NodeID : string 
}

Response body (RDP or rdpticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string, 
    SessionID : int, 
    NodeID : string 
}

Response body (rdpfile)

RDP file as an attachment.

Response body details

  • ID: The Session Token (same as Ticket).
  • Ticket: The Session Token (same as ID).
  • Host: The target Host Name.
  • Port: The target Host Port.
  • TicketAtHost: Formatted value: {Ticket}@{Host}
  • Link: Formatted ssh link - ssh://{Ticket}@{Host}:{Port}
  • Command: Formatted ssh command: ssh -p {Port} {Ticket}@{Host}
  • SessionID: ID of the Session.
  • NodeID: ID of the Session Node.

Response codes

201 – Request successful. Session details or RDP file in the response body.

403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access.

For more information, please see Common response codes.