API v2: Safes

Safe directly regulates user access to monitored servers. It specifies available protocols’ features, policies and other details concerning users and servers relations.

Data structures

SafeModel

Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier
name	string	yes	Unique safe’s name
blocked	boolean; default value false	yes
reason	string	if blocked == true
login_reason	boolean; default value false	yes	Enable sending login reason for connection
use_ticketing_system	boolean; default value false	yes
require_confirmation	boolean; default value false	yes	Enable confirmation of each connection
otp_in_access_gateway	boolean; default value true	yes	Enable generating OTP in the Access Gateway
webclient	boolean; default value true	yes	Enable connecting to the session in browser
confirmation_timeout	number; default value 5	yes
inactivity_limit	number; default value 0	yes
time_limit	number; default value 0	yes
note_access	string {none, read, write}; default value none	Access level to the notes
required_votes	number; default value 0	yes	How many voters will be voting for the access request
backup_id	string	no	Target destination ID for storing session data
rdp	SafeRDPAttributes	If protocol == rdp
ssh	SafeSSHAttributes	If protocol == ssh
vnc	SafeVNCAttributes	If protocol == vnc
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only
last_login	datetime		Read-only
accounts	object-array		Read-only; expensive to use; JSON object array containing id, name, and type of assigned accounts.
builtin	boolean		Read-only; expensive to use; if true, the object is not editable.
hidden	boolean		Read-only; expensive to use; if true, the object is hidden in UI.

SafeRDPAttributes

Attribute	Type	Required	Description
rdp_audin	boolean; default value true	yes	Audio input redirection
rdp_cliprdr	boolean; default value true	yes	Clipboard redirection
rdp_depth	number	no	Max. color depth
rdp_rdpdr	boolean; default value true	yes
rdp_rdpsnd	boolean; default value true	yes	Sound redirection
rdp_rdrynvc	boolean; default value true	yes
rdp_resolution	string	no	Max. resolution
rdp_suspend	boolean; default value true	yes	Enable content to not be available for viewing when the user minimizes its client application
rdp_tsmf	boolean; default value true	yes

SafeSSHAttributes

Attribute	Type	Required
ssh_agent	boolean; default value true	yes
ssh_environment	boolean; default value true	yes
ssh_exec	boolean; default value true	yes
ssh_port_forwarding	boolean; default value true	yes
ssh_scp	boolean; default value true	yes
ssh_session	boolean; default value true	yes
ssh_shell	boolean; default value true	yes
ssh_sftp	boolean; default value true	yes
ssh_terminal	boolean; default value true	yes
ssh_x11	boolean; default value true	yes

SafeVNCAttributes

Attribute	Type	Required	Description
vnc_clipcli	boolean; default value true	yes	Enable a user to be allowed to paste text into the VNC server computer
vnc_clipsrv	boolean; default value true	yes	Enable a user to be allowed to copy and paste text from the VNC server computer into the user’s computer

Request for retrieving available attributes of the SafeModel

Method	GET
Path	/api/v2/objspec/safe

UserSafeAssignmentModel

Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier.
user_id	string	yes	Immutable. Uniqueness is required in the combination of attribute user_id with attribute safe_id.
safe_id	string	yes	Immutable. Uniqueness is required in the combination of attribute safe_id with attribute user_id.
blocked	boolean; default value false	yes
position	number
password_visible	boolean; default value false	yes	Allow a user to use Secret Checkout feature and view passwords in the Access Gateway.
use_time_policy	boolean; default value false	yes
valid_since	datetime (h:m:s); default value -infinity	yes	Beginning access time.
valid_to	datetime (h:m:s); default value infinity	yes	Ending access time.
user_name	string		Read-only; Expensive to use.
safe_name	string		Read-only; Expensive to use.
created_at	datetime		Read-only.
modified_at	datetime		Read-only.
removed	boolean		Read-only.
builtin	boolean		Read-only; Expensive to use; If true, the object is not editable.
hidden	boolean		Read-only; Expensive to use; If true, the object is hidden in UI.

Request for retrieving available attributes of the UserSafeAssignmentModel

Method	GET
Path	/api/v2/objspec/user_safe

UserSafeTimePolicyAssignmentModel

Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier.
user_safe_id	string		Read-only object Identifier.
user_id	string	yes	Immutable.
safe_id	string	yes	Immutable.
day_of_week	number	yes	Value range from 1 to 7.
valid_from	datetime (h:m:s)	yes	Beginning access time.
valid_to	datetime (h:m:s)	yes	Ending access time.
created_at	datetime		Read-only.
modified_at	datetime		Read-only.
removed	boolean		Read-only.

Request for retrieving available attributes of the UserSafeTimePolicyAssignmentModel

Method	GET
Path	/api/v2/objspec/user_safe_time_policy

AccountSafeListenerAssignmentModel

Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier
account_id	string	yes	Immutable. Uniqueness is required in the combination of attribute account_id with attributes safe_id and listener_id.
safe_id	string	yes	Immutable. Uniqueness is required in the combination of attribute safe_id with attributes account_id and listener_id.
listener_id	string	no	Immutable. Uniqueness is required in the combination of attribute listener_id with attributes account_id and safe_id.
account_name	string		Read-only; expensive to use
account_type	string		Read-only; expensive to use
protocol	string		Read-only; expensive to use
server_id	string		Read-only; expensive to use; null if pool is assigned.
server_name	string		Read-only; expensive to use; null if pool is assigned.
pool_id	string		Read-only; expensive to use; null if server is assigned.
pool_name	string		Read-only; expensive to use; null if server is assigned.
safe_name	string		Read-only; expensive to use
listener_name	string		Read-only; expensive to use
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only
builtin	boolean		Read-only; expensive to use; if true, the object is not editable.
hidden	boolean		Read-only; expensive to use; if true, the object is hidden in UI.

Request for retrieving available attributes of the AccountSafeListenerAssignmentModel

Method	GET
Path	/api/v2/objspec/account_safe_listener

SafeGrantAssignmentModel

Attribute	Type	Required	Description
id	string		Read-only, protected object Identifier
to_user_id	string	yes	Immutable. Expects unique for_safe_id
for_safe_id	string	yes	Immutable. Expects unique to_user_id
for_safe_name	string		Read-only, expensive to use
to_user_name	string		Read-only, expensive to use
to_user_role	string		Read-only, expensive to use
created_at	string		Read-only
modified_at	string		Read-only
removed	boolean		Read-only

Request for retrieving available attributes of the SafeGrantAssignmentModel

Method	GET
Path	/api/v2/objspec/safe_grant

Note

To check allowed methods, available URL parameters and possible responses please refer to the API overview section.

The next chapter describes procedures for creating separate requests.

Refer to the Batch operations topic to create nested requests for operating on the Safe objects.

Retrieving safes list

Request

Method	GET
Path	/api/v2/safe

Example request

Sending GET https://10.0.0.0/api/v2/safe

Response

    { "result": "success",
"safe": [
    {
        "id": "123678819172646913",
        "name": "main",
        "blocked": false,
        "login_reason": false,
        "use_ticketing_system": false,
        "require_confirmation": false,
        "otp_in_access_gateway": true,
        "webclient": true,
        "confirmation_timeout": 5,
        "inactivity_limit": 0,
        "time_limit": 0,
        "note_access": "none",
        "required_votes": 0,
        "rdp_audin": true,
        "rdp_cliprdr": true,
        "rdp_rdpdr": true,
        "rdp_rdpsnd": true,
        "rdp_rdrynvc": true,
        "rdp_suspend": true,
        "rdp_tsmf": true,
        "ssh_agent": true,
        "ssh_environment": true,
        "ssh_exec": true,
        "ssh_port_forwarding": true,
        "ssh_scp": true,
        "ssh_session": true,
        "ssh_shell": true,
        "ssh_sftp": true,
        "ssh_terminal": true,
        "ssh_x11": true,
        "vnc_clipcli": true,
        "vnc_clipsrv": true,
        "created_at": "2022-10-20 02:01:38.366865-07",
        "modified_at": "2022-10-26 03:26:45.530129-07",
        "last_login": "-infinity",
        "accounts": [
            "122678819172646913",
            "1232678819172646914",
            "1232678819172646919"
        ]}]}

Creating a safe

Request

Method	POST
Path	/api/v2/safe
Headers	Content-Type: Application/JSON
Body	SafeModel

Example request

Sending POST https://10.0.0.0/api/v2/safe

{ "name": "my-1st-safe" }

Response

    { "result": "success",
"safe": {
    "id": "1232678819172646915" }}

Retrieving a safe

Request

Method	GET
Path	/api/v2/safe/<id>

Example request

Sending GET https://10.0.0.0/api/v2/safe/1232678819172646915

Response

    { "result": "success",
"safe": {
    "id": "1232678819172646915",
    "name": "my-1st-safe",
    "blocked": false,
    "login_reason": false,
    "use_ticketing_system": false,
    "require_confirmation": false,
    "otp_in_access_gateway": true,
    "webclient": true,
    "confirmation_timeout": 5,
    "inactivity_limit": 0,
    "time_limit": 0,
    "note_access": "none",
    "required_votes": 0,
    "rdp_audin": true,
    "rdp_cliprdr": true,
    "rdp_rdpdr": true,
    "rdp_rdpsnd": true,
    "rdp_rdrynvc": true,
    "rdp_suspend": true,
    "rdp_tsmf": true,
    "ssh_agent": true,
    "ssh_environment": true,
    "ssh_exec": true,
    "ssh_port_forwarding": true,
    "ssh_scp": true,
    "ssh_session": true,
    "ssh_shell": true,
    "ssh_sftp": true,
    "ssh_terminal": true,
    "ssh_x11": true,
    "vnc_clipcli": true,
    "vnc_clipsrv": true,
    "created_at": "2022-10-27 02:26:22.951762-07",
    "modified_at": "2022-10-27 02:26:22.951762-07",
    "last_login": "-infinity" }}

Modifying a safe

Request

Method	PATCH
Path	/api/v2/safe/<id>
Headers	Content-Type: Application/JSON
Body	SafeModel

Example request: Enabling the Just-in-Time feature for a safe that would wait for 5 authorized users to vote for access

Sending PATCH https://10.0.0.0/api/v2/safe/1232678819172646915

{ "required_votes": 5}

Response

{ "result": "success" }

Retrieving users’ time policy settings within safes

Request

Method	GET
Path	/api/v2/user/safe/time_policy

Example request

Sending GET https://10.0.0.0/api/v2/user/safe/time_policy

Response (User’s time policy is declared separately for each day)

    {
"result": "success",
"user_safe_time_policy": [
    {
        "id": "4602678819172646913",
        "safe_id": "4602678819172646913",
        "user_id": "1232678819172646915",
        "day_of_week": 2, <--- A user has access to the safe on Tuesday
        "valid_from": "09:00:00", <--- User's access starts at 9:00
        "valid_to": "14:00:00", <--- and ends at 14:00
        "created_at": "2022-10-26 02:25:19.155648-07",
        "modified_at": "2022-10-26 02:30:40.677788-07"
    },
    {
        "id": "4602678819172646914",
        "safe_id": "4602678819172646913",
        "user_id": "1232678819172646915",
        "day_of_week": 3, <--- A user has access to the safe on Wednesday
        "valid_from": "09:15:00", <--- User's access starts at 9:15
        "valid_to": "14:15:00", <--- and ends at 14:15
        "created_at": "2022-10-26 02:32:11.781045-07",
        "modified_at": "2022-10-26 02:32:11.781045-07"
    }]}

Modifying a user’s time policy settings within a safe

Request

Method	PATCH
Path	/api/v2/user/safe/time_policy/<id>
Body	UserSafeTimePolicyAssignment

Example request: Changing the day of user’s access to Monday

Sending PATCH https://10.0.0.0/api/v2/user/safe/time_policy/1232678819172646913

{ "day_of_week": 1}

Response

{ "result": "success" }

Retrieving user’s settings within a safe

Request

Method	GET
Path	/api/v2/user/<user_id>/safe/<safe_id>

Modifying a user within a safe

Request

Method	PATCH
Path	/api/v2/user/<user_id>/safe/<safe_id>
Body	UserSafeAssignment

Example request: Allow a user to use Secret Checkout feature and view passwords in the Access Gateway

Sending PATCH https://10.0.0.0/api/v2/user/1232678819172646914/safe/12302678819172646913

{"password_visible": true}

Response

{ "result": "success" }

Deleting a user from a safe

Request

Method	DELETE
Path	/api/v2/user/<user_id>/safe/<safe_id>

Retrieving users allowed to manage selected safe

Request

Method	GET
Path	/api/v2/user/safe

Granting management privileges

Request

Method	POST
Path	/api/v2/grant/safe
Body	{ to_user_id: 1234567890, for_safe_id: 1234567891 }

Retrieving account-safe-listener assignments list

Request

Method	GET
Path	/api/v2/account/safe/listener

Creating an account-safe-listener assignments

Request

Method	POST
Path	/api/v2/account/safe/listener
Headers	Content-Type: Application/JSON
Body	AccountSafeListenerAssignmentModel

Example request

Sending POST https://10.0.0.0/api/v2/account/safe/listener

    { "account_id": 1232678819172646919,
"safe_id": 1232678819172646913,
"listener_id": 1232678819172646914 }

Response

    { "result": "success",
"account_safe_listener": {} }

Deleting an account-safe-listener assignment

Request

Method	DELETE
Path	/api/v2/account/<account_id>/safe/<safe_id>/listener/<listener_id>

Deleting a safe

Request

Method	DELETE
Path	/api/v2/safe/<id>