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
Parameter 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

Request for retrieving available attributes of the UserModel

Method 
GET
Path 
/api/v2/objspec/user
UserSafeAssignmentModel
Parameter Type Required Description
id string yes Read-only object Identifier
user_id string yes Immutable. Expects unique safe_id
safe_id string yes Immutable. Expects unique user_id
blocked boolean; default value false yes  
position number yes  
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
created_at datetime   Read-only
modified_at datetime   Read-only
removed boolean   Read-only

Request for retrieving available attributes of the UserSafeAssignmentModel

Method 
GET
Path 
/api/v2/objspec/user_safe
UserSafeTimePolicyAssignmentModel
Parameter 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
Parameter Type Required Description
id string   Read-only, protected object Identifier
to_user_id string yes Immutable. Expects unique for_safe_id
for_user_id string yes Immutable. Expects unique to_safe_id
to_user_name string   Read-only, expensive to use
for_user_name 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

Allowed methods

GET for reading data of an existing object; no request body is required
POST for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
PATCH for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
DELETE for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

  • fields - for including the object fields in the query,

  • filter - narrows out the result with available additions:

    • in - include possible field values (separated with comma),
    • match - include a sequence of characters to be searched in field values,
    • eq - equal,
    • ne - not equal,
    • lt - less than,
    • le - less or equal,
    • gt - greater than,
    • ge - greater than or equal
    • blocked - filter blocked objects,
    • !blocked - filter unblocked objects,
    • isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

  • order,

  • offset,

  • limit,

  • debug - for showing statistics, database errors, etc,

  • total_count,

  • reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count


Possible responses

Code Status  
200 success OK
201 success CREATED
400 failure BAD REQUEST; message examples: Unrecognized endpoint, Request body is not allowed for this endpoint
401 failure UNAUTHORIZED
404 failure BAD REQUEST; message example: Object not found

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>