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`¶
Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier
name	string	yes	Unique account’s name
description	string	no	Object description
note	string		Read-only; expensive to use
blocked	boolean; default value `false`	yes
reason	string	if `blocked` == `true`
type	string {regular, forward, anonymous}	yes	Immutable
category	string {nonprivileged, privileged}
protocol	string		Protocol of the pool or server which the account is assigned to. Read-only; expensive to use.
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
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`
method	string {account, passvn, password, sshkey}	if `type` == `regular \|\| forward`	Authentication method
domain	string	if `type` == `regular \|\| forward`
login	string; may be empty	if `type` == `regular`
secret	string; may be empty	no
private_key_passphrase	string	with `secret`	Passphrase to use to decrypt private key. Protected.
ssh_public_key	string		SSH public key. Read-only; expensive to use.
ssh_fingerprint_sha256	string		SSH key SHA256 fingerprint. Read-only; expensive to use.
forward_domain	boolean; default value `false`	if `type` == `forward`
servauth	boolean; default value `false`	if `type` == `forward`	Authentication against server
account_id	string	if `method` == `account`
passvn_id	string	if `method` == `passvn`
passvn_name	string		Read-only; expensive to use
dump_mode	string {all, none, raw, noraw}; default value `noraw`	yes	Session recording options
retention_locked	boolean; default value `false`	yes
retention_remove	number		Value range from `1` to `2147483647`.
retention_external	number		Value range from `1` to `2147483647`.
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
password_lastupdate	datetime		Read-only
password_lastcheck	datetime		Read-only
password_change _policy_id	string	if `type` == `regular`	Password change policy identifier.
password_change _policy_name	string		Password change policy name. Read-only; expensive to use.
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_change_trigger_pending	boolean		Waiting for password change after triggered. Read-only; expensive to use.
password_change_trigger_available	boolean		Can manually trigger password change request? Read-only; expensive to use.
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	boolean		Read-only
last_login	datetime		Read-only; expensive to use
safes	object-array		JSON object array containing `id`, `name`, and `position` of assigned safes. Read-only; expensive to use.
safes_ids	string-array		Read-only; hidden; expensive to use
safe_names	string-array		Read-only; hidden; expensive to use
servers	object-array		Read-only; expensive to use; JSON object array containing `id`, `mask`, `name`, `port` and `address` of assigned servers.
servers_ids	string-array		Read-only; hidden; expensive to use
servers_names	string-array		Read-only; hidden; expensive to use
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.
state	string {created, discovered, onboarded, quarantined}		Account’s discovery state: discovered, onboarded, quarantined, or created (for manually created accounts). Read-only. Expensive to use.
discovered_at	string		Account discovered at timestamp. Read-only; expensive to use
onboarded_at	string		Account onboarded at timestamp. Read-only; expensive to use.
onboarded_by_id	string		User identifier who onboarded this account. ARead-only; expensive to use.
onboarded_by_name	string		User name who onboarded this account. Read-only; expensive to use.
quarantined_at	string		Account quarantined at timestamp. Read-only; expensive to use.
quarantined_by_id	string		User identifier who quarantined this account. Read-only; expensive to use.
quarantined_by_name	string		User name who quarantined this account. Read-only; expensive to use.
quarantine_reason	string		Quarantine reason. Read-only; expensive to use.
scanner_id	string		Scanner identifier. Read-only; expensive to use.
scanner_name	string		Scanner name. Read-only; expensive to use.
secret_exposed	boolean		Determines if there is a user who checked out the current password and now has lost access to the account, e.g. the user is now blocked, deleted, or there is no longer a safe containing both the user and the account, and gives the user secret check out rights. Read-only; expensive to use.

Request for Retrieving Available Attributes of the AccountModel

Method	GET
Path	/api/v2/objspec/account

`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

`AccountGrantAssignmentModel`¶
Attribute	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`
for_account_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	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only

Request for Retrieving Available Attributes of the AccountGrantAssignmentModel

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

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

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

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>

Managing Security Alerts¶

Request

Method	POST
Path	/api/v2/account/<account_id>/mark_sessions_as_safe