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

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-Safe Assignment¶

Request

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

Delete User¶

Request

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