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

UserModel

Attribute	Type	Required	Description
id	string	yes	Read-only object identifier. Requires read, modify, or delete right on object type user, depending on the HTTP method used (GET, PATCH, or DELETE respectively).
name	string	yes	Unique user’s name
blocked	boolean; default value false	yes
reason	string	if blocked == true
domain	string	no	User’s domain
privileges	string-array		Read-only
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
user_directory_id	string	no	Id of the user’s LDAP server
source_ip	string	no
pubkey_ec	string	with pubkey_rsa	Value format: public key.
pubkey_rsa	string	with pubkey_ec	Value format: public key.
pubkey_fingerprint	string		Read-only; expensive to use. Fingerprint of user’s public keys.
pubkey_trusted_by	string
pubkey_trusted_at	string		Read-only
invite_code	string		Read-only
invite_code_expires_at	string		Read-only
invited_by	string		Read-only
fudo_network	boolean		Read-only; expensive to use.
oidc_subs	object-array		OpenID Connect sub claims. Read-only. Expensive.
roles	object-array		Read-only. Expensive to use.
role_names	string-array		Read-only. Hidden. Expensive to use.
role_ids	string-array		Read-only. Hidden. Expensive to use.
safes	object-array		Read-only; expensive to use; JSON object array containing id, name, and position of assigned safes.
safes_ids	string-array		Read-only; hidden; expensive to use
safe_names	string-array		Read-only; hidden; expensive to use
authentication_methods	object-array		Read-only; expensive to use; JSON object array containing id, type, and position of configured authentication methods.
rights	string-array		Read-only; list of rights the subject has to this object.
created_at	datetime		Read-only. Timestamp of creation.
modified_at	datetime		Read-only. Timestamp of modification.
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.

Get Available Attributes of the UserModel

Request

Method	GET
Path	/api/v2/objspec/user

Data Structures: UserSafeAssignmentModel

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. Requires read right on object type user for GET, POST, PATCH, and DELETE requests.
roles	object-array		Read-only. Expensive to use.
role_names	string-array		Read-only. Hidden. Expensive to use.
role_ids	string-array		Read-only. Hidden. Expensive to use.
safe_id	string	yes	Immutable. Uniqueness is required in the combination of attribute safe_id with attribute user_id. Requires read right on object type safe for GET and PATCH requests, user-add right for POST, and user-remove right for DELETE requests.
blocked	boolean; default value false	yes	Access to this safe is disabled for the user.
position	number
password_visible	boolean; default value false	yes	Allow a user to use Secret Checkout feature and view passwords in the Access Gateway.
time_policy_checksum	string		Read-only; Expensive to use. Checksum computed from time policies used for this user-safe connection.
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.
user_domain	string		Read-only; Expensive to use.
user_email	string		Read-only; Expensive to use.
user_organization	string		Read-only; Expensive to use.
user_domain	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.

Retrieve Available Attributes of the UserSafeAssignmentModel

Request

Method	GET
Path	/api/v2/objspec/user_safe

Data Structures: UserSafeTimePolicyAssignmentModel

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. Requires read right on object type user for GET requests, and modify right for POST, PATCH, and DELETE requests.
safe_id	string	yes	Immutable. Requires read right on object type safe for GET, POST, and PATCH requests.
user_name	string		Read-only; Expensive to use.
user_role	string		Read-only; Expensive to use.
safe_name	string		Read-only; Expensive to use.
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.

Retrieve Available Attributes of the UserSafeTimePolicy - AssignmentModel

Request

Method	GET
Path	/api/v2/objspec/user_safe_time_policy

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.

Refer to the Batch operations topic to create nested requests for operating on the User objects.

Create a User

Request

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

Example Request

POST /api/v2/user

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

Response

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

Get Users List

Request

Method	GET
Path	/api/v2/user

Example Request

GET /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"
    }
]}

Get a User

Request

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

Modify a User

Request

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

Example Request: Changing User Login

PATCH /api/v2/user/<id>

{
"name": "new-user"
}

Response

{ "result": "success"}

Example Request: Blocking a User

PATCH /api/v2/user/<id>

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

Response

{ "result": "success" }

Get User-Safe Assignments List

Request

Method	GET
Path	/api/v2/user/safe

Create a User-Safe Assignment

Request

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

Example Request

POST /api/v2/user/safe

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

Response

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

Get Users’ Time Policy Settings Within Safes

Request

Method	GET
Path	/api/v2/user/safe/time_policy

Example Request

GET /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"
    }]}

Get Users’ Time Policy Settings Within Safes by ID

Request

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

Example Request

GET /api/v2/user/safe/time_policy/<id>

Response (User’s time policy is declared separately for each day)

    {
"result": "success",
"user_safe_time_policy": [
    {
        "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"
    }]}

Modify 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

PATCH /api/v2/user/safe/time_policy/<id>

{ "day_of_week": 1}

Response

{ "result": "success" }

Create 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

POST /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" }}

Delete User’s Time Policy Settings Within a Safe

Request

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

Delete User-Safe Assignment

Request

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

Delete User

Request

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