Development > Server API > 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
See also:
