Сотрудники и организация

Все методы · Ключи и права · Ошибки

Примеры ответов сокращены. Пустой массив означает допустимый результат без доступных записей, а не обязательное отсутствие данных.

Для методов с ключом действуют общие проверки: 401 — ключ не принят, 403 — не хватает scope или прав владельца, 429 — превышен лимит. Неверные параметры могут дать 400, недоступный адресный ресурс — 404. Особенности команды указаны рядом с методом. Точную причину смотрите в error.code и details: как обработать ошибку и безопасно повторить запрос.

Все методы этого раздела, включая POST, дополнительно требуют права администрирования пользователей у владельца ключа. Scope identity:read или identity:write сам по себе недостаточен.

Получить сотрудников

GET /api/v1/identity/users

Действие ключа: identity:read. Оно не заменяет права владельца на объекты и поля.

Дополнительно нужны права администрирования пользователей.

Параметры пути: нет. Тело: не требуется.

Пример запроса

GET /api/v1/identity/users HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив identity users.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать сотрудника

POST /api/v1/identity/users

Действие ключа: identity:write. Оно не заменяет права владельца на объекты и поля.

Обязательны login, displayName, корректный email. Дополнительно userId, locale, timezone, employeeId, externalId. Метод не выдаёт пароль и не назначает роль.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/identity/users HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "login": "example-user",
  "displayName": "Учебный пользователь",
  "email": "user@example.invalid"
}

Ответ и ошибки

Успех: 201. Identity user.

{
  "data": {
    "id": "USER_ID",
    "login": "example-user",
    "state": "ACTIVE"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Получить команды

GET /api/v1/identity/groups

Действие ключа: identity:read. Оно не заменяет права владельца на объекты и поля.

Дополнительно нужны права администрирования пользователей.

Параметры пути: нет. Тело: не требуется.

Пример запроса

GET /api/v1/identity/groups HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив групп.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать команду

POST /api/v1/identity/groups

Действие ключа: identity:write. Оно не заменяет права владельца на объекты и поля.

Обязательны code, name; groupId необязателен. Членство создаётся отдельным методом.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/identity/groups HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "code": "example-team",
  "name": "Учебная команда"
}

Ответ и ошибки

Успех: 201. Группа.

{
  "data": {
    "id": "GROUP_ID",
    "code": "example-team",
    "name": "Учебная команда",
    "state": "ACTIVE"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Получить отделы

GET /api/v1/identity/org-units

Действие ключа: identity:read. Оно не заменяет права владельца на объекты и поля.

Дополнительно нужны права администрирования пользователей.

Параметры пути: нет. Тело: не требуется.

Пример запроса

GET /api/v1/identity/org-units HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив подразделений.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать отдел

POST /api/v1/identity/org-units

Действие ключа: identity:write. Оно не заменяет права владельца на объекты и поля.

name обязателен; code генерируется при отсутствии. Дополнительно organizationUnitId, parentId, managerUserId, location.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/identity/org-units HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Учебный отдел"
}

Ответ и ошибки

Успех: 201. Отдел.

{
  "data": {
    "id": "ORG_ID",
    "name": "Учебный отдел",
    "state": "ACTIVE"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Добавить участника команды

POST /api/v1/identity/group-memberships

Действие ключа: identity:write. Оно не заменяет права владельца на объекты и поля.

memberType=user (по умолчанию) или group. Циклы вложенных групп запрещены. Дополнительно проверяется риск наследования ролей.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/identity/group-memberships HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "groupId": "GROUP_ID",
  "memberId": "USER_ID",
  "memberType": "user"
}

Ответ и ошибки

Успех: 201. Членство.

{
  "data": {
    "id": "MEMBERSHIP_ID",
    "groupId": "GROUP_ID",
    "memberId": "USER_ID",
    "memberType": "user"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Назначить или сменить отдел

POST /api/v1/identity/org-memberships

Действие ключа: identity:write. Оно не заменяет права владельца на объекты и поля.

Один отдел на сотрудника. Для перевода передайте expectedOrganizationUnitId текущего отдела. Второе назначение без этого поля и устаревший ID возвращают HTTP 409; повтор текущего назначения не меняет запись.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/identity/org-memberships HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "organizationUnitId": "ORG_ID",
  "userId": "USER_ID"
}

Ответ и ошибки

Успех: 201. Членство отдела.

{
  "data": {
    "id": "MEMBERSHIP_ID",
    "organizationUnitId": "ORG_ID",
    "userId": "USER_ID"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Связанные статьи

• Обзор API
• Права доступа
• Интеграции