Method for Working with API User Accounts

To work with APU user accounts, execute requests using the "accounts" API method (determine administrator token before executing the request):

Add an API user account:

curl -X POST '<IP address or DNS server name>/api/v2/accounts/<user authentication type>/' --header'Content-Type: application/json' -H 'Authorization: Bearer <administrator token>' -d '{
    "username": "<user login>",
    "password": "<user password>",
    "confirmed_password": "<confirm user password>",
    "full_name": "<user full name>",
    "is_active": <indicates whether user is active (true/false)>,
    "project_id": <project identifier>,
    "api_groups": [<array of identifiers of groups, in which the user is included>],
    "ds_credentials": [<array of credentials identifiers>],
    "dss_username": "<DSS account login if required>",
    "is_blocked": <indicates whether user is locked (true/false)>,
    "ttl": <account expiration date (days)>,
    "max_password_ttl": <maximum password validity period (days)>
}'

In substitutions:

<user authentication type>. Use the values:

local-users. Locally.
ldap-users. LDAP server.
datasource-users. Server <data source name in project>.

Depending on the user authentication type, one determines availability of the password, confirmed_password, full_name, is_active, parameters. The password, confirmed_password and full_name parameters are available only for the user with the Local authentication type. The is_active parameter is available only for the user with the Local or <data source name in project> Server authentication type.

<array of identifiers of groups, in which the user is included>. Use values of id parameters returned on getting a list of all groups of users in project.
<array of credentials identifiers>. Use values of id parameters returned on getting a list of all credentials in project.

NOTE. If the API user is included in the group of users with specified credentials for data source, credentials for a specific API user are not set for the same data source. The user cannot be included in several groups with specified credentials for the same data source.

<project identifier>. Use value of id parameter returned on getting a list of all projects.

The project_id parameter can be replaced with two parameters:

project_name. Name of the project, which contains the user.
environment_name. Name of the environment that contains the project.

The example of response:

{
    "username": "new_local",
    "full_name": "new_local_FIO",
    "is_active": true,
    "project_id": 9,
    "api_groups": [
        19
    ],
    "ds_credentials": [
        297
    ],
    "dss_username": "",
    "project_name": "proj",
    "environment_name": "env",
    "is_blocked": false,
    "ttl": 1,
    "max_password_ttl": 1,
    "lock_expire_date": null,
    "expire_date": null,
    "password_expire_date": "2024-01-27",
    "id": 727
}

Values of parameters contain the following additional information about the user:

lock_expire_date. Date, before which the user is locked. If the user is not locked, the system returns Null.
expire_date. Date, before which user account is valid. If user account is valid forever, the system returns Null.
password_expire_date. Date, before use password is valid.
id. User identifier.

Get information about specific API user account:

curl -X GET '<IP address or DNS server name>/api/v2/accounts/<user authentication type>/{<identifier of requested user>}/' --header 'Content-type: application/json' -H 'Authorization: Bearer <administrator token>'

In the <requested user identifier> substitution use value of the id parameter returned on getting a list of all API user accounts.

The example of response:

{
    "username": "user",
    "full_name": "",
    "is_active": true,
    "project_id": 9,
    "api_groups": [],
    "ds_credentials": [],
    "dss_username": "",
    "project_name": "my_proj",
    "environment_name": "my_env",
    "is_blocked": false,
    "ttl": null,
    "max_password_ttl": null,
    "lock_expire_date": null,
    "expire_date": null,
    "password_expire_date": null,
    "id": 725
}

Change API user account:

curl -X PATCH '<IP address or DNS server name>/api/v2/accounts/<user authentication type>/{<identifier of requested user>}/' --header 'Content-Type: application/json' -H 'Authorization: Bearer <administrator token>' -d '{
    "username": "<user login>",
    "password": "<user password>",
    "confirmed_password": "<confirm user password>",
    "full_name": "<user full name>",
    "is_active": <indicates whether user is active (true/false)>,
    "api_groups": [<array of identifiers of groups, in which the user is included>],
    "ds_credentials": [<array of credentials identifiers>],
    "dss_username": "<DSS account login if required>",
    "is_blocked": <indicates whether user is locked (true/false)>,
    "ttl": <account expiration date (days)>,
    "max_password_ttl": <maximum password validity period (days)>
}'

In the <requested user identifier> substitution use value of the id parameter returned on getting a list of all API user accounts.

Depending on the user authentication type one determines availability of the password, confirmed_password, full_name, is_active parameters. The password, confirmed_password and full_name parameters are available only for the user with the Local authentication type. The is_active parameter is available only for the user with the Local or <data source name in project> Server authentication type.

The example of response:

{
    "username": "new_user",
    "full_name": "new_name",
    "is_active": true,
    "project_id": 9,
    "api_groups": [
        19
    ],
    "ds_credentials": [
        297
    ],
    "dss_username": "",
    "project_name": "proj",
    "environment_name": "env",
    "is_blocked": false,
    "ttl": 1,
    "max_password_ttl": 1,
    "lock_expire_date": null,
    "expire_date": "2024-01-27",
    "password_expire_date": "2024-01-27",
    "id": 725
}

Search for user in connected LDAP directory:

curl -X GET '<IP address or DNS server name>/api/v1/admin/ldap/search-user/?username=<user login or part of user login>' --header 'Content-Type: application/json' -H 'Authorization: Bearer <administrator token>'

The example of response:

[
    {
        "email": "",
        "fullName": "user01",
        "isActive": true,
        "label": "test\\user01",
        "sid": "S-1-5-21-4010739491-1455226807-1877500552-1110",
        "value": "test\\user01"
    },{
        "email": "",
        "fullName": "user02",
        "isActive": true,
        "label": "test\\user02",
        "sid": "S-1-5-21-817733621-3753459759-1615796639-1107",
        "value": "test\\user02"
    }
]

Get list of all API user accounts:

curl -X GET '<IP address or DNS server name>/api/v2/accounts/users/' --header 'Content-type: application/json' -H 'Authorization: Bearer <administrator token>'

The example of response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [{
        "id": 647,
        "username": "ds_user",
        "full_name": "",
        "is_active": false,
        "is_ldap": false,
        "is_blocked": false,
        "api_groups": [],
        "auth_data_source": 12,
        "project": "proj_demo",
        "environment": "env_dev",
        "devices_count": 0
    },{
        "id": 721,
        "username": "user01",
        "full_name": "user01",
        "is_active": true,
        "is_ldap": true,
        "is_blocked": false,
        "api_groups": [],
        "auth_data_source": null,
        "project": "proj_demo",
        "environment": "env_dev",
        "devices_count": 0
    }]
}

Values of parameters contain the following additional information about each API user account:

is_ldap. Indicates whether the user has the LDAP Server authentication type.
auth_data_source. Data source identifier if the Server <data source name in project> user authentication type is used.
devices_count. The number of mobile devices linked to the user.

To filter answer, use query parameters in the request:

environment. Filtering by environment name.
project. Filtering by project name.
full_name. Filtering by user full name.
username. Filtering by user login.
search. Filtering by user full name and login.
is_active. Filtering by user activity in the system.
page_size. Filtering by the number of objects on a page.
page. Filtering by the number of page with results.

Delete API user account:

curl -X DELETE '<IP address or DNS server name>/api/v2/accounts/users/<identifier of requested user>/' --header 'Content-Type: application/json' -H 'Authorization: Bearer <administrator token>'

In the <requested user identifier> substitution use value of the id parameter returned on getting a list of all API user accounts.

The example of response:

204 No Content