API v2: Accounts

Account defines the privileged account existing on the monitored server. It specifies the actual login credentials, user authentication mode: anonymous (without user authentication), regular (with login credentials substitution) or forward (with login and password forwarding); password changing policy as well as the password changer itself.


Data structures

AccountModel
Parameter Type Required Description
id string yes Read-only object Identifier
name string yes Unique account’s name
description string no Object description
blocked boolean; default value false yes  
reason string if blocked == true  
type string {regular, forward, anonymous} yes Immutable
hotseat boolean; default value false if type == regular Enable to be informed about existing connections via the Access Gateway. Available for the server with protocol == rdp
login string; may be empty if type == regular  
domain string if type == regular || forward  
forward_domain boolean; default value false if type == forward  
servauth boolean; default value false if type == forward Authentication against server
method string {account, passvn, password, sshkey} if type == regular || forward Authentication method
account_id string if method == account  
passvn_id string if method == passvn  
category string {nonprivileged, privileged}    
server_id string yes  
server_name string   Read-only; expensive to use
server_address string   Read-only; expensive to use
server_mask number   Read-only; expensive to use
server_port number   Read-only; expensive to use
pool_id string yes  
pool_name string   Read-only; expensive to use
secret string; may be empty no  
dump_mode string {all, none, raw, noraw}; default value noraw yes Session recording options
retention_locked boolean; default value false yes  
timestamp_enabled boolean; default value false yes  
ocr_enabled boolean; default value false yes  
ocr_lang string {eng, pol, deu, hun, nor, rus, ukr}; if more than 1, separated by the + symbol if ocr_enabled == true  
ssh_agent boolean; default value false yes  
retention_remove number    
retention_external number    
password_lastupdate datetime   Read-only
password_lastcheck datetime   Read-only
password_change _policy_id string if type == regular  
password_checkout _time_limit datetime (h:m:s) if password_change _on_checkin == true  
password_change _on_checkin boolean   If set, password will be changed after last password checkin.
password_change _on_session_end boolean   If set, password will be changed after session finishes.
password_recovery boolean   If set and password verification detects unknown password, password changer will try to recover the password to a known value.
created_at datetime   Read-only
modified_at datetime   Read-only
removed bolean   Read-only
last_login datetime   Read-only; expensive to use
safes string-array   Read-only; expensive to use
servers string-array   Read-only; expensive to use

Request for retrieving available attributes of the AccountModel

Method 
GET
Path 
/api/v2/objspec/account
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
AccountGrantAssignmentModel
Parameter Type Required Description
id string   Read-only, protected object Identifier
to_user_id string yes Immutable. Expects unique for_account_id
for_account_id string yes Immutable. Expects unique to_user_id
to_user_name string   Read-only, expensive to use
for_account_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 AccountGrantAssignmentModel

Method 
GET
Path 
/api/v2/objspec/account_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 Account objects.


Creating an account

Request

Method 
POST
Path 
/api/v2/account
Headers 
Content-Type: Application/JSON
Body 
AccountModel

Example request

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

{
"name": "test-account",
"type": "regular",
"server_id": "1234567890",
"method": "password",
"login":"test-account-login",
"domain": "my-domain"
        }

Response

    {
"result": "success",
"account": {
    "id": "1234567890123456"
            }}

Retrieving accounts list

Request

Method 
GET
Path 
/api/v2/account

Retrieving an account

Request

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

Modifying an account

Request

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

Example request: Enable OCR with German, English and Polish languages for an account

Sending PATCH https://10.0.0.0/api/v2/account/1234567890123456

    { "ocr_enabled": true,
"ocr_lang": "deu+eng+pol"}

Response

{"result": "success"}

Granting access for user to account

Request

Method 
POST
Path 
/api/v2/grant/account
Headers 
Content-Type: Application/JSON
Body 
{
to_user_id: 1234567890,
for_account_id: 1234567891
}

Adding a password changer policy to account

Password changer policy can’t be created via API, but can be assigned to a particular Account. It requires a password changer or/and password verifier assigned according to it’s enabled options.

By default there is an existing password policy named Static, without restrictions with id = 1, which has no password change or verification functions assigned.

Request

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

Example request

Sending https://10.0.0.0/api/v2/account/1234567890123456

{"domain":null, "password_change_policy_id":"2345678901234567"}

Response

{"result": "success"}

Modifying password change parameters for account

Request

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

Example request

Sending https://10.0.0.0/api/v2/account/1234567890123456798

{
   "domain":null,
   "password_change_policy_id":"2345678901234567989",
   "password_checkout_time_limit":"06:59:00",
   "password_change_on_session_end":true,
   "password_change_on_checkin":true,
   "password_recovery":true
}

Response

{"result": "success"}

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 an account

Request

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