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
Parameter 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 string-array   Read-only; expensive to use
SafeRDPAttributes
Parameter 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
Parameter 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
Parameter 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
Parameter Type Required Description
id string yes Read-only object Identifier
user_id string yes Immutable. Expects unique safe_id
safe_id string yes Immutable. Expects unique user_id
blocked boolean; default value false yes  
position number yes  
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
created_at datetime   Read-only
modified_at datetime   Read-only
removed boolean   Read-only

Request for retrieving available attributes of the UserSafeAssignmentModel

Method 
GET
Path 
/api/v2/objspec/user_safe
UserSafeTimePolicyAssignmentModel
Parameter 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
Parameter Type Required Description
id string yes Read-only object Identifier
account_id string yes Immutable. Expects unique safe_id and listener_id
safe_id string yes Immutable. Expects unique account_id and listener_id
listener_id string no Immutable. Expects unique account_id and safe_id
valid_to datetime    
created_at datetime   Read-only
modified_at datetime   Read-only
removed boolean   Read-only

Request for retrieving available attributes of the AccountSafeListenerAssignmentModel

Method 
GET
Path 
/api/v2/objspec/account_safe_listener
SafeGrantAssignmentModel
Parameter 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
to_user_name string   Read-only, expensive to use
for_safe_name 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

Allowed methods

GET for reading data of an existing object; no request body is required
POST for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
PATCH for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
DELETE for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

  • fields - for including the object fields in the query,

  • filter - narrows out the result with available additions:

    • in - include possible field values (separated with comma),
    • match - include a sequence of characters to be searched in field values,
    • eq - equal,
    • ne - not equal,
    • lt - less than,
    • le - less or equal,
    • gt - greater than,
    • ge - greater than or equal
    • blocked - filter blocked objects,
    • !blocked - filter unblocked objects,
    • isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

  • order,

  • offset,

  • limit,

  • debug - for showing statistics, database errors, etc,

  • total_count,

  • reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count


Possible responses

Code Status  
200 success OK
201 success CREATED
400 failure BAD REQUEST; message examples: Unrecognized endpoint, Request body is not allowed for this endpoint
401 failure UNAUTHORIZED
404 failure BAD REQUEST; message example: Object not found

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>