API v2: Users

User defines a subject entitled to connect to servers within monitored IT infrastructure. Detailed object definition (i.e. unique login and domain combination, full name, email address etc.) enables precise accountability of user actions when login and password are substituted with a shared account login credentials.

Data structures

UserModel

Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier
name	string	yes	Unique user’s name
blocked	boolean; default value false	yes
reason	string	if blocked == true
domain	string	no	User’s domain
role	string {admin, operator, service, superadmin, user}	yes
full_name	string	no	User’s full name
email	string	no	User’s email address
organization	string	no	User’s organization name
phone	string	no	User’s phone number
ad_domain	string	no	User’s AD domain
ldap_base	string	no	User’s LDAP base
language	string {en, pl, ru, ua, kk}; default value en	yes	Interface language
previous_success	datetime		Read-only
last_success	datetime		Read-only
last_failure	datetime		Read-only
failures	number; default value 0	yes	Number of authentication failures
password_complexity	boolean; default value false	yes	Enable password complexity settings
external_sync	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
ldap_server_id	string	no	Id of the user’s LDAP server
source_ip	string	no
snmp_enabled	boolean; default value false	if role == service
snmp_authentication		if role == service & snmp_enabled == true
snmp_encryption		if role == service & snmp_enabled == true
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only
safes	object-array		Read-only; expensive to use; JSON object array containing id, name, and position of assigned safes.
authentication_methods	object-array		Read-only; expensive to use; JSON object array containing id, type, and position of configured authentication methods.
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 UserModel

Method	GET
Path	/api/v2/objspec/user

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

UserGrantAssignmentModel

Attribute	Type	Required	Description
id	string		Read-only, protected object Identifier
to_user_id	string	yes	Immutable. Expects unique for_user_id
for_user_id	string	yes	Immutable. Expects unique to_user_id
for_user_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 UserGrantAssignmentModel

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

Creating a user

Request

Method	POST
Path	/api/v2/user
Headers	Content-Type: Application/JSON
Body	UserModel

Example request

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

{
"role": "user",
"name": "test-user",
"language":"en"
 }

Response

    {
"result": "success",
"user": {
    "id": "12345678901234567890"
}}

Retrieving users list

Request

Method	GET
Path	/api/v2/user

Example request

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

Response

    {
"result": "success",
"user": [
    {
        "id": "1234567891012345",
        "name": "tet",
        "blocked": false,
        "role": "user",
        "full_name": "",
        "email": "",
        "phone": "",
        "ad_domain": "",
        "ldap_base": "",
        "language": "en",
        "failures": 0,
        "password_complexity": false,
        "external_sync": false,
        "valid_since": "-infinity",
        "valid_to": "infinity",
        "created_at": "2022-10-20 02:09:49.818029-07",
        "modified_at": "2022-10-20 02:09:49.818029-07"
    },
    {
        "id": "12345678910123456",
        "name": "admin",
        "blocked": false,
        "role": "superadmin",
        "language": "en",
        "previous_success": "2022-10-25 05:33:19.377878-07",
        "last_success": "2022-10-25 06:03:39.084783-07",
        "last_failure": "2022-10-24 04:19:35.204557-07",
        "failures": -1,
        "password_complexity": false,
        "external_sync": false,
        "valid_since": "-infinity",
        "valid_to": "infinity",
        "created_at": "2022-10-20 02:01:32.093269-07",
        "modified_at": "2022-10-25 06:03:39.085472-07"
    }
]}

Retrieving a user

Request

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

Modifying a user

Request

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

Example request: Changing user login

Sending PATCH https://10.0.0.0/api/v2/user/12345678901234567890

{
"name": "new-user"
}

Response

{ "result": "success"}

Example request: Blocking a user

Sending PATCH https://10.0.0.0/api/v2/user/12345678901234567890

{"blocked": true,
 "reason": "lost rights"}

Response

{ "result": "success" }

Retrieving user’s management privileges

Request

Method	GET
Path	/api/v2/grant/<to_user_id>/user/<for_user_id> /api/v2/grant/<to_user_id>/server/<for_server_id> /api/v2/grant/<to_user_id>/safe/<for_safe_id> /api/v2/grant/<to_user_id>/pool/<for_pool_id> /api/v2/grant/<to_user_id>/listener/<for_listener_id> /api/v2/grant/<to_user_id>/account/<for_account_id>

Revoking user’s management privileges

Request

Method	DELETE
Path	/api/v2/grant/<to_user_id>/user/<for_user_id> /api/v2/grant/<to_user_id>/server/<for_server_id> /api/v2/grant/<to_user_id>/safe/<for_safe_id> /api/v2/grant/<to_user_id>/pool/<for_pool_id> /api/v2/grant/<to_user_id>/listener/<for_listener_id> /api/v2/grant/<to_user_id>/account/<for_account_id>

Granting access for user to another user

Request

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

Retrieving user-safe assignments list

Request

Method	GET
Path	/api/v2/user/safe

Creating a user-safe assignment

Request

Method	POST
Path	/api/v2/user/safe
Body	UserSafeAssignment

Example request

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

{ "user_id": "1232678819172646915",
        "safe_id": "1232678819172646913" }

Response

    { "result": "success",
"user_safe": {} }

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": "4602678819172646914",
        "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": "4602678819172646914",
        "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 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" }

Creating user’s time policy settings within a safe

Request

Method	POST
Path	/api/v2/user/safe/time_policy
Body	UserSafeTimePolicyAssignment

Example request: Creating user’s access to the the safe for Thursday from 16:00 till 23:00

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

{ "user_id": "1232678819172646915",
"safe_id": "1232678819172646913",
"day_of_week": 4,
"valid_from": "16:00:00",
"valid_to": "23:00:00"
}

Response

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

Deleting a user-safe assignment

Request

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

Deleting a user

Request

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