Enterprise Recon v1 API

All Documentation > Enterprise Recon v1 API > Users and Roles

Users and Roles

Use this set of APIs to retrieve detailed information on users and user roles.

List Users

Get information about all or a specific user. Returned information includes user login name, email address, active domain directory and permissions granted to the user.
Full list of users can only be retrieved by users with Global Admin, System Manager and Permissions Manager permissions.

Request

GET

https://er-master:8339/v1/users/{user_id}

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
user_id	string	Specify User ID of User to retrieve data for. If no value is specified, response returns data for all users. user_id is the id response item from the /v1/users endpoint.

Query Parameters

Parameter	Data Type	Description
user_name	string	Filter results with matching User name. Partial matching allowed. If no value is defined, query will return results for all users.
details	boolean default: false	Show (true) or hide (false) certain user details including email address, job title, phone number and active domain directory.
offset	integer default: 0	The first User to return data for. For offset=N, data will be fetched starting from the Nth User. If no value is specified or offset=0, query will return data from the very first User. Results are sorted by User ID in ascending order. Not applicable if a User ID is specified in the path.
limit	integer default: 1000 max: 100000	Maximum number of Users to return data for, starting from the first record determined by the offset parameter value. Not applicable if a User ID is specified in the path.

Header Parameters

Parameter	Data Type	Description
Accept-Encoding	string enum: gzip deflate	Specify the compression algorithm to use on the response object. Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Parameter

Data Type

Description

Accept-Encoding

string

enum: gzip deflate

Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP

GET /v1/users?details=true
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/users?details=true' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Unique user ID. This ID is unique 20 digit number.
name	string	User's login name.
full_name	string	User's full name.
role_ids	array <string>	List of roles IDs assigned to the User. role_id is the id response item from the /v1/roles endpoint.
email	string	User's email address. Returned if details=true.
title	string	User's job title. Returned if details=true.
department	string	User's department. Returned if details=true.
phone	string	User's phone number. Returned if details=true.
domain	string	User's active directory domain. Returned if details=true.
ad_auth	boolean enum: true false	Indicates if Active Directory authentication is enabled for user. Returned if details=true.
2fa_enabled	boolean enum: true false	This field is true if two-factor authentication (2FA) has been enabled and the User has completed the 2FA setup. Returned if details=true.
enabled	boolean enum: true false	Indicates if the user account is enabled. Returned if details=true.
pdf_page_size	string enum: letter A4	Preferred PDF report page size setting. Returned if details=true.
permissions	array <object>	Array of global and resource permissions associated with the user role or user account. Returned if details=true.
permissions/id	string	Unique Group ID, Target ID, Target location ID or Credential ID associated with the resource permission. Not applicable for global permissions, or if resource permission is applicable to all resources for a given resource type.
permissions/action	string	Global permission or resource permission. Use together with permissions->id parameter. Not applicable for global permissions or if the resource permission is applicable to all resources for a given resource type. For example, Global Administrator permissions: action=global administrator. permissions->id field is not required. Summary Reporting permissions for all Targets: action=report summary. permissions->id field is not required. Scan permissions to a specific Target: id=<target_id> and action=scan schedule. Edit permissions for a specific credential set: id=<credential_id> and action=credential_edit. See Permissions or User Permissions for more information.
permissions/path	string	Specific path on the Group or Target that the user role or user account has permissions to.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "332768006779777470",
    "name": "admin",
    "full_name": "Administrator",
    "role_ids": [
      "8211329127068321466",
      "9702229190474382700",
      "11814414398501530574"
    ],
    "email": "admin@example.com",
    "title": "<job title>",
    "department": "<department>",
    "phone": "<phone number>",
    "domain": "<AD domain>",
    "ad_auth": false,
    "2fa_enabled": false,
    "enabled": true,
    "pdf_page_size": "letter",
    "permissions": [
      {
        "action": "global administrator"
      }
    ]
  },
  {
    "id": "14534282168541960155",
    "name": "userA",
    "full_name": "User A",
    "role_ids": [
      "9702229190474382700",
      "11814414398501530574"
    ],
    "email": "userA@example.com",
    "title": "Software Developer",
    "department": "Engineering",
    "phone": "12345678",
    "domain": "",
    "ad_auth": false,
    "2fa_enabled": false,
    "enabled": true,
    "pdf_page_size": "a4",
    "permissions": [
      {
        "action": "system manager"
      },
      {
        "action": "api access"
      },
      {
        "id": "6669346926546261115",
        "action": "credential edit"
      },
      {
        "id": "11584308467558502228",
        "action": "remediation mark location"
      },
      {
        "action": "scan schedule"
      },
      {
        "id": "2328966531556234228",
        "action": "scan schedule",
        "path": "mssql://database1/schema1/table1"
      }
    ]
  }
]

Update a User

Update user details including full name, email address, job title, department and phone number.

Request

PUT

https://er-master:8339/v1/users/<user_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
user_id	string	Specify User ID of User to update. user_id is the id response item from the /v1/users endpoint.

Request Schema

If a field is omitted in the request body, it will be cleared.

Response Item	Data Type	Description
name	string	User's login name.
password	string	User's login password. Minimum password complexity requirements is dependent on the Password Policy settings. Existing password will not be changed if this field is not provided in the request.
full_name	string	User's full name.
role_ids	array <string>	List of roles IDs assigned to the User. role_id is the id response item from the /v1/roles endpoint.
email	string	User's email address.
title	string	User's job title.
department	string	User's department.
phone	string	User's phone number.
2fa_enabled	boolean enum: true false	Set true to turn on two-factor authentication for the user.
pdf_page_size	string enum: letter A4	Preferred PDF report page size setting.
permissions	array <object>	Array of global and resource permissions associated with the user role or user account.
permissions/id	string	Unique Group ID, Target ID, Target location ID or Credential ID associated with the resource permission. Not applicable for global permissions, or if resource permission is applicable to all resources for a given resource type.
permissions/action	string	Global permission or resource permission. Use together with permissions->id parameter. Not applicable for global permissions or if the resource permission is applicable to all resources for a given resource type. For example, Global Administrator permissions: action=global administrator. permissions->id field is not required. Summary Reporting permissions for all Targets: action=report summary. permissions->id field is not required. Scan permissions to a specific Target: id=<target_id> and action=scan schedule. Edit permissions for a specific credential set: id=<credential_id> and action=credential_edit. See Permissions or User Permissions for more information.
permissions/path	string	Specific path on the Group or Target that the user role or user account has permissions to.

Request Samples

HTTP

PUT /v1/users/332768006779777470
Content-Type: application/json
{
  "name": "userA",
  "full_name": "User A",
  "role_ids": [
    "9702229190474382700",
    "11814414398501530574"
  ],
  "email": "userA@example.com",
  "title": "Software Developer",
  "department": "Engineering",
  "phone": "12345678",
  "2fa_enabled": false,
  "pdf_page_size": "a4",
  "permissions": [
    {
      "action": "system manager"
    },
    {
      "action": "api access"
    },
    {
      "id": "6669346926546261115",
      "action": "credential edit"
    },
    {
      "id": "11584308467558502228",
      "action": "remediation mark location"
    },
    {
      "action": "scan schedule"
    },
    {
      "id": "2328966531556234228",
      "action": "scan schedule",
      "path": "mssql://database1/schema1/table1"
    }
  ]
}

cURL

curl --request PUT 'https://er-master:8339/v1/users/332768006779777470' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "userA",
  "full_name": "User A",
  "role_ids": [
    "9702229190474382700",
    "11814414398501530574"
  ],
  "email": "userA@example.com",
  "title": "Software Developer",
  "department": "Engineering",
  "phone": "12345678",
  "2fa_enabled": false,
  "pdf_page_size": "a4",
  "permissions": [
    {
      "action": "system manager"
    },
    {
      "action": "api access"
    },
    {
      "id": "6669346926546261115",
      "action": "credential edit"
    },
    {
      "id": "11584308467558502228",
      "action": "remediation mark location"
    },
    {
      "action": "scan schedule"
    },
    {
      "id": "2328966531556234228",
      "action": "scan schedule",
      "path": "mssql://database1/schema1/table1"
    }
  ]
}'

Response Samples

204 No Content

422 Unprocessable Entity

Returned if the request body contains invalid values or formats in the input fields.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid input for '{fieldname}'."
}  

List Current User

Get current user details (e.g. login name, email address, active domain directory and permissions).

Request

GET

https://er-master:8339/v1/users/me

Authorization

Basic Authentication

Query Parameters

Parameter	Data Type	Description
details	boolean default: false	Show (true) or hide (false) certain user details including email address, job title, phone number and active domain directory.

Parameter

Data Type

Description

details

boolean

default: false

Show (true) or hide (false) certain user details including email address, job title, phone number and active domain directory.

Header Parameters

Parameter	Data Type	Description
Accept-Encoding	string enum: gzip deflate	Specify the compression algorithm to use on the response object. Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Parameter

Data Type

Description

Accept-Encoding

string

enum: gzip deflate

Request Samples

HTTP

GET /v1/users/me?details=true
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/users/me?details=true' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Unique user ID. This ID is unique 20 digit number.
name	string	User's login name.
full_name	string	User's full name.
role_ids	array <string>	List of roles IDs assigned to the User. role_id is the id response item from the /v1/roles endpoint.
email	string	User's email address. Returned if details=true.
title	string	User's job title. Returned if details=true.
department	string	User's department. Returned if details=true.
phone	string	User's phone number. Returned if details=true.
domain	string	User's active directory domain. Returned if details=true.
ad_auth	boolean enum: true false	Indicates if Active Directory authentication is enabled for user. Returned if details=true.
2fa_enabled	boolean enum: true false	This field is true if two-factor authentication (2FA) has been enabled and the User has completed the 2FA setup. Returned if details=true.
enabled	boolean enum: true false	Indicates if the user account is enabled. Returned if details=true.
pdf_page_size	string enum: letter A4	Preferred PDF report page size setting. Returned if details=true.
permissions	array <object>	Array of global and resource permissions associated with the user role or user account. Returned if details=true.
permissions/id	string	Unique Group ID, Target ID, Target location ID or Credential ID associated with the resource permission. Not applicable for global permissions, or if resource permission is applicable to all resources for a given resource type.
permissions/action	string	Global permission or resource permission. Use together with permissions->id parameter. Not applicable for global permissions or if the resource permission is applicable to all resources for a given resource type. For example, Global Administrator permissions: action=global administrator. permissions->id field is not required. Summary Reporting permissions for all Targets: action=report summary. permissions->id field is not required. Scan permissions to a specific Target: id=<target_id> and action=scan schedule. Edit permissions for a specific credential set: id=<credential_id> and action=credential_edit. See Permissions or User Permissions for more information.
permissions/path	string	Specific path on the Group or Target that the user role or user account has permissions to.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "14534282168541960155",
    "name": "userA",
    "full_name": "User A",
    "role_ids": [
      "9702229190474382700",
      "11814414398501530574"
    ],
    "email": "userA@example.com",
    "title": "Software Developer",
    "department": "Engineering",
    "phone": "12345678",
    "domain": "",
    "ad_auth": false,
    "2fa_enabled": false,
    "enabled": true,
    "pdf_page_size": "a4",
    "permissions": [
      {
        "action": "system manager"
      },
      {
        "action": "api access"
      },
      {
        "id": "6669346926546261115",
        "action": "credential edit"
      },
      {
        "id": "11584308467558502228",
        "action": "remediation mark location"
      },
      {
        "action": "scan schedule"
      },
      {
        "id": "2328966531556234228",
        "action": "scan schedule",
        "path": "mssql://database1/schema1/table1"
      }
    ]
  }
]

Update Current User

Update current user details including full name, email address, job title, department and phone number.

Request

PUT

https://er-master:8339/v1/users/me

Authorization

Basic Authentication

Request Schema

If a field is omitted in the request body, it will be cleared.

Response Item	Data Type	Description
name	string	User's login name.
password	string	User's login password. Minimum password complexity requirements is dependent on the Password Policy settings. Existing password will not be changed if this field is not provided in the request.
full_name	string	User's full name.
role_ids	array <string>	List of roles IDs assigned to the User. role_id is the id response item from the /v1/roles endpoint.
email	string	User's email address.
title	string	User's job title.
department	string	User's department.
phone	string	User's phone number.
2fa_enabled	boolean enum: true false	Set true to turn on two-factor authentication for the user.
pdf_page_size	string enum: letter A4	Preferred PDF report page size setting.
permissions	array <object>	Array of global and resource permissions associated with the user role or user account.
permissions/id	string	Unique Group ID, Target ID, Target location ID or Credential ID associated with the resource permission. Not applicable for global permissions, or if resource permission is applicable to all resources for a given resource type.
permissions/action	string	Global permission or resource permission. Use together with permissions->id parameter. Not applicable for global permissions or if the resource permission is applicable to all resources for a given resource type. For example, Global Administrator permissions: action=global administrator. permissions->id field is not required. Summary Reporting permissions for all Targets: action=report summary. permissions->id field is not required. Scan permissions to a specific Target: id=<target_id> and action=scan schedule. Edit permissions for a specific credential set: id=<credential_id> and action=credential_edit. See Permissions or User Permissions for more information.
permissions/path	string	Specific path on the Group or Target that the user role or user account has permissions to.

Request Samples

HTTP

PUT /v1/users/me
Content-Type: application/json
{
  "name": "userA",
  "full_name": "User A",
  "role_ids": [
    "9702229190474382700",
    "11814414398501530574"
  ],
  "email": "userA@example.com",
  "title": "Software Developer",
  "department": "Engineering",
  "phone": "12345678",
  "2fa_enabled": false,
  "pdf_page_size": "a4",
  "permissions": [
    {
      "action": "system manager"
    },
    {
      "action": "api access"
    },
    {
      "id": "6669346926546261115",
      "action": "credential edit"
    },
    {
      "id": "11584308467558502228",
      "action": "remediation mark location"
    },
    {
      "action": "scan schedule"
    },
    {
      "id": "2328966531556234228",
      "action": "scan schedule",
      "path": "mssql://database1/schema1/table1"
    }
  ]
}

cURL

curl --request PUT 'https://er-master:8339/v1/users/me' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "userA",
  "full_name": "User A",
  "role_ids": [
    "9702229190474382700",
    "11814414398501530574"
  ],
  "email": "userA@example.com",
  "title": "Software Developer",
  "department": "Engineering",
  "phone": "12345678",
  "2fa_enabled": false,
  "pdf_page_size": "a4",
  "permissions": [
    {
      "action": "system manager"
    },
    {
      "action": "api access"
    },
    {
      "id": "6669346926546261115",
      "action": "credential edit"
    },
    {
      "id": "11584308467558502228",
      "action": "remediation mark location"
    },
    {
      "action": "scan schedule"
    },
    {
      "id": "2328966531556234228",
      "action": "scan schedule",
      "path": "mssql://database1/schema1/table1"
    }
  ]
}'

Response Samples

204 No Content

422 Unprocessable Entity

Returned if the request body contains invalid values or formats in the input fields.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid input for '{fieldname}'."
}  

Delete a User

Delete an existing user account.

Request

DELETE

https://er-master:8339/v1/users/<user_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
user_id	string	Specify User ID of User to delete. user_id is the id response item from the /v1/users endpoint.

Request Samples

HTTP

DELETE /v1/users/332768006779777470
Content-Type: application/json

cURL

curl --request DELETE 'https://er-master:8339/v1/users/332768006779777470' \
--user apiuser:password123 \
--header "Content-Type: application/json"

Response Samples

204 No Content

Add a New User

Add a user account. Specify the user name, password, and other optional details (e.g. full name, email address, job title, department, permissions) in the request body.

Request

POST

https://er-master:8339/v1/users

Authorization

Basic Authentication

Request Schema

Response Item	Data Type	Description
name	string	User's login name.
password	string	User's login password. Minimum password complexity requirements is dependent on the Password Policy settings.
full_name	string	User's full name.
role_ids	array <string>	List of roles IDs assigned to the User. role_id is the id response item from the /v1/roles endpoint.
email	string	User's email address.
title	string	User's job title.
department	string	User's department.
phone	string	User's phone number.
2fa_enabled	boolean enum: true false	Set true to turn on two-factor authentication for the user.
pdf_page_size	string enum: letter A4	Preferred PDF report page size setting.
permissions	array <object>	Array of global and resource permissions associated with the user role or user account.
permissions/id	string	Unique Group ID, Target ID, Target location ID or Credential ID associated with the resource permission. Not applicable for global permissions, or if resource permission is applicable to all resources for a given resource type.
permissions/action	string	Global permission or resource permission. Use together with permissions->id parameter. Not applicable for global permissions or if the resource permission is applicable to all resources for a given resource type. For example, Global Administrator permissions: action=global administrator. permissions->id field is not required. Summary Reporting permissions for all Targets: action=report summary. permissions->id field is not required. Scan permissions to a specific Target: id=<target_id> and action=scan schedule. Edit permissions for a specific credential set: id=<credential_id> and action=credential_edit. See Permissions or User Permissions for more information.
permissions/path	string	Specific path on the Group or Target that the user role or user account has permissions to.

Request Samples

HTTP

POST /v1/users
Content-Type: application/json
{
  "name": "userA",
  "password": "userA_password",
  "full_name": "User A",
  "role_ids": [
    "9702229190474382700",
    "11814414398501530574"
  ],
  "email": "userA@example.com",
  "title": "Software Developer",
  "department": "Engineering",
  "phone": "12345678",
  "2fa_enabled": false,
  "pdf_page_size": "a4",
  "permissions": [
    {
      "action": "system manager"
    },
    {
      "action": "api access"
    },
    {
      "id": "6669346926546261115",
      "action": "credential edit"
    },
    {
      "id": "11584308467558502228",
      "action": "remediation mark location"
    },
    {
      "action": "scan schedule"
    },
    {
      "id": "2328966531556234228",
      "action": "scan schedule",
      "path": "mssql://database1/schema1/table1"
    }
  ]
}

cURL

curl --request POST 'https://er-master:8339/v1/users' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "userA",
  "password": "userA_password",
  "full_name": "User A",
  "role_ids": [
    "9702229190474382700",
    "11814414398501530574"
  ],
  "email": "userA@example.com",
  "title": "Software Developer",
  "department": "Engineering",
  "phone": "12345678",
  "2fa_enabled": false,
  "pdf_page_size": "a4",
  "permissions": [
    {
      "action": "system manager"
    },
    {
      "action": "api access"
    },
    {
      "id": "6669346926546261115",
      "action": "credential edit"
    },
    {
      "id": "11584308467558502228",
      "action": "remediation mark location"
    },
    {
      "action": "scan schedule"
    },
    {
      "id": "2328966531556234228",
      "action": "scan schedule",
      "path": "mssql://database1/schema1/table1"
    }
  ]
}'

Response Schema

201 Created

Response Item	Data Type	Description
id	string	User ID assigned to the newly created User.

Response Samples

201 Created

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
  "id": "12345678901234567890"
}  

List Roles

Get information for all or a specific user role. Returned information includes role ID, name, list of users assigned to the role, and permissions associated with the role.

Request

GET

https://er-master:8339/v1/roles/{role_id}

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
role_id	string	Specify Role to retrieve data for. If no value is specified, response returns data for all roles. role_id is the id response item from the /v1/roles endpoint.

Query Parameters

Parameter	Data Type	Description
role_name	string	Filter results with matching Role name. Partial matching allowed. If no value is defined, query will return results for all roles.
details	boolean default: false	Show (true) or hide (false) certain role details including users assigned to a role and permissions associated with the role.
offset	integer default: 0	The first Role to return data for. For offset=N, data will be fetched starting from the Nth Role. If no value is specified or offset=0, query will return data from the very first Role. Results are sorted by Role ID in ascending order. Not applicable if a Role ID is specified in the path.
limit	integer default: 1000 max: 100000	Maximum number of Roles to return data for, starting from the first record determined by the offset parameter value. Not applicable if a Role ID is specified in the path.

Header Parameters

Parameter	Data Type	Description
Accept-Encoding	string enum: gzip deflate	Specify the compression algorithm to use on the response object. Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Parameter

Data Type

Description

Accept-Encoding

string

enum: gzip deflate

Request Samples

HTTP

GET /v1/roles?details=true
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/roles?details=true' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Unique Role ID. This ID is unique 20 digit number.
name	string	Role name.
permissions	array <object>	Array of global and resource permissions associated with the user role or user account.
permissions/id	string	Unique Group ID, Target ID, Target location ID or Credential ID associated with the resource permission. Not applicable for global permissions, or if resource permission is applicable to all resources for a given resource type.
permissions/action	string	Global permission or resource permission. Use together with permissions->id parameter. Not applicable for global permissions or if the resource permission is applicable to all resources for a given resource type. For example, Global Administrator permissions: action=global administrator. permissions->id field is not required. Summary Reporting permissions for all Targets: action=report summary. permissions->id field is not required. Scan permissions to a specific Target: id=<target_id> and action=scan schedule. Edit permissions for a specific credential set: id=<credential_id> and action=credential_edit. See Permissions or User Permissions for more information.
permissions/path	string	Specific path on the Group or Target that the user role or user account has permissions to.
user_ids	array <string>	List of User IDs associated with the Role. user_id is the id response item from the /v1/users endpoint. Returned if details=true.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
    {
        "id": "7203410202732939738",
        "name": "Scan All Targets",
        "permissions": [
            {
                "action": "scan schedule"
            },
            {
                "id": "11584308467558502228",
                "action": "credential use"

            },
            {
                "action": "system manager"
            },
            {
                "action": "permission manager"
            },
            {
                "action": "datatype manager"
            }
        ],
        "user_ids": [
            "10872241356641061056",
            "11430461549459420676",
            "12081157656550955624"
        ]
    },
    {
        "id": "15689106429100432238",
        "name": "API Access",
        "permissions": [
            {
                "action": "api access"
            }
        ],
        "user_ids": [
            "5668657335739656574"
        ]
    }
]