Users (users)

Overview

Manages user accounts.

In requests to a specific user endpoint, the alias "current" may be specified. In this case the authorized user’s identifier is automatically used instead.

The account password (the 'pwd' field) is masked when returned to administrators and is not returned to other users with roles granting read access to the collection.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/iam/users

Creating a new user

GET

/rest/v1/iam/users

Getting the list of users

GET

/rest/v1/iam/users/<id> /rest/v1/iam/users/current

Getting user data

PATCH

/rest/v1/iam/users/<id> /rest/v1/iam/users/current

Modifying user data

DELETE

/rest/v1/iam/users/<id>

Deleting a user

LOOKUP

/rest/v1/iam/users

Searching for a user identifier


Creating a new user

Request

Field description: user entity

Example request
POST /rest/v1/iam/users HTTP/1.1
Content-Type: application/json; charset=utf-8

{
"name": "Maria Ivanova",
  "login": "mari",
  "pwd": "hjpjdstckjys"
}

Response

Field description: user entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "6a941fb6-016c-bdc2-95ce-50e54938780c",
"name": "Maria Ivanova",
  "login": "mari",
  "pwd": "*****",
  "timezone": "default",
  "opts": {
    "title": "",
    "roles": [],
    "tags": [],
    "comment": "",
    "allow_script_crud": false
  },
  "ext": {
    "ct": "2019-08-23T09:17:23.46Z",
    "lwt": "2019-08-23T09:17:23.46Z"
  }
}

Getting the list of users

Request

Table 1. Request parameters
Name Type Description

filter

object

Filter by field values.

mask

str

List of fields to output. Available fields for output: id, login, name, timezone, opts.roles, ext.lwt, ext.ct.

offset

int

Offset in the list of resources to output.

limit

int

Maximum number of resources in the list.

order

array<object|str>

Sorting order of resources in the list.

flat

bool

Transformation of composite fields to flat form.

Example request
GET /rest/v1/iam/users?offset=0&limit=2 HTTP/1.1

Response

Field description: user entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": "6a941fb6-016c-bdc2-95ce-50e54938780c",
"name": "Maria Ivanova",

    "login": "mari",
    "timezone": "default",
    "opts": {
      "roles": []
    },
    "ext": {
      "ct": "2019-08-23T09:17:23.46Z",
      "lwt": "2019-08-23T09:17:23.46Z"
    }
  },
  {
    "id": "e7adf0aa-05b7-8163-948c-3392a9660db9",

    "name": "Peter Bukashin",
    "login": "peter",
    "timezone": 3.0,
    "opts": {
      "roles": ["admin"]
    },
    "ext": {
      "ct": "2019-08-21T07:18:33.29Z",
      "lwt": "2019-08-21T07:18:33.29Z"
    }
  }
]

Getting user data

Specifics

  • The server does not return the actual password value, hiding it with the value "*****".

Request

Table 2. Request parameters
Name Type Description

mask

str

List of fields to output.

flat

bool

Transformation of composite fields to flat form.

Example request
GET /rest/v1/iam/users/6a941fb6-016c-bdc2-95ce-50e54938780c HTTP/1.1

Response

Field description: user entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "6a941fb6-016c-bdc2-95ce-50e54938780c",
"name": "Maria Ivanova",
  "login": "mari",
  "pwd": "*****",
  "timezone": "default",
  "opts": {
    "title": "",
    "roles": ["admin","monitor","scripteditor"],
    "tags": [],
    "comment": "",
    "allow_script_crud": false
  },
  "ext": {
    "ct": "2019-08-23T09:17:23.46Z",
    "lwt": "2019-08-23T09:17:23.46Z"
  }
}

Modifying user data

Fields prohibited for modification: id

Specifics

  • When saving a user with the masking value "*****" in the password field, the password is not changed.

Request

Field description: user entity

Example request
PATCH /rest/v1/iam/users/6a941fb6-016c-bdc2-95ce-50e54938780c HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "opts": {
    "roles": ["admin","monitor","scripteditor"]
  }
}

Response

Field description: user entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "6a941fb6-016c-bdc2-95ce-50e54938780c",
"name": "Maria Ivanova",
  "login": "mari",
  "pwd": "*****",
  "timezone": "default",
  "opts": {
    "title": "",
    "roles": ["admin","monitor","scripteditor"],
    "tags": [],
    "comment": "",
    "allow_script_crud": false
  },
  "ext": {
    "ct": "2019-08-23T09:17:23.46Z",
    "lwt": "2019-09-06T12:46:18.62Z"
  }
}

Deleting a user

Request

Example request
DELETE /rest/v1/iam/users/6a941fb6-016c-bdc2-95ce-50e54938780c HTTP/1.1

Response

Example response
HTTP/1.1 204 No Content

Searching for a user identifier

Searches for a resource by the specified key and returns the identifier(s) for building the endpoint.

Key fields for search: id, login

Request

Example request
LOOKUP /rest/v1/iam/users HTTP/1.1
Content-Type: application/json; charset=utf-8

"mari"

Response

Example successful response
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[
  "6a941fb6-016c-bdc2-95ce-50e54938780c"
]
Example failed response
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1404,
  "error_message": "Lookup failed"
}