API v2: Accounts¶
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¶
Attribute | 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 | boolean | Read-only | |
last_login | datetime | Read-only; expensive to use | |
safes | object-array | Read-only; expensive to use; JSON object array containing id , name , and position of assigned safes. |
|
servers | object-array | Read-only; expensive to use; JSON object array containing id , mask , name , port and address of assigned servers. |
|
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 | Account’s discovery state: discovered, onboarded, quarantined or created (for manually created accounts). Read-only. Expensive to use. |
Request for retrieving available attributes of the AccountModel
Method | GET
|
Path | /api/v2/objspec/account
|
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
|
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 | 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
|
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"
}}
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>
|