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 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 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 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.

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 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.