Management API

REST API для программного управления пользователями, приложениями, ролями и API-ресурсами вашего realm.

Базовый URL: https://your-domain.com/api/v1/{realmUUID}

Аутентификация

Management API использует M2M (Machine-to-Machine) токены. Получите токен через client_credentials grant:

curl -X POST https://your-domain.com/oauth2/{realmUUID}/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=users:read users:write roles:read"

Ответ:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Используйте токен во всех запросах к API:

curl https://your-domain.com/api/v1/{realmUUID}/users \
  -H "Authorization: Bearer {access_token}"

подсказка

Запрашивайте только необходимые скоупы. Доступные скоупы: users:read, users:write, users:roles, applications:read, applications:write, roles:read, roles:write, resources:read, resources:write.

Формат ошибок

Все ошибки возвращают единую JSON-структуру:

{
  "error": "not_found",
  "message": "User not found"
}

Основные HTTP-коды:

Код	Значение
400	Некорректное тело запроса или параметры
401	Отсутствует или невалидный токен
403	У токена нет требуемого скоупа
404	Ресурс не найден
422	Ошибка валидации

---

Users API

Базовый путь: /api/v1/{realmUUID}/users

Метод	Путь	Скоуп	Описание
GET	/users	users:read	Список пользователей (с пагинацией)
POST	/users	users:write	Создать пользователя
GET	/users/{id}	users:read	Получить пользователя
PATCH	/users/{id}	users:write	Обновить пользователя
DELETE	/users/{id}	users:write	Удалить пользователя
PATCH	/users/{id}/password	users:write	Сменить пароль
PATCH	/users/{id}/is-suspended	users:write	Заблокировать/разблокировать
GET	/users/{id}/roles	users:roles	Роли пользователя
POST	/users/{id}/roles	users:roles	Назначить роли
DELETE	/users/{id}/roles/{roleId}	users:roles	Удалить роль
GET	/users/{id}/identities	users:read	Подключенные провайдеры

Список пользователей

curl "https://your-domain.com/api/v1/{realmUUID}/users?page=1&per_page=20&search=john" \
  -H "Authorization: Bearer {token}"

{
  "data": [
    {
      "id": "01HQ...",
      "email": "john@example.com",
      "name": "John Doe",
      "is_suspended": false,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1
  }
}

Создать пользователя

curl -X POST https://your-domain.com/api/v1/{realmUUID}/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe",
    "password": "securePassword123"
  }'

Обновить пользователя

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/users/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith"}'

Сменить пароль

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/users/{id}/password \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"password": "newSecurePassword456"}'

Заблокировать/разблокировать пользователя

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/users/{id}/is-suspended \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"is_suspended": true}'

Назначить роли пользователю

curl -X POST https://your-domain.com/api/v1/{realmUUID}/users/{id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_ids": ["role-uuid-1", "role-uuid-2"]}'

Удалить роль у пользователя

curl -X DELETE https://your-domain.com/api/v1/{realmUUID}/users/{id}/roles/{roleId} \
  -H "Authorization: Bearer {token}"

---

Applications API

Базовый путь: /api/v1/{realmUUID}/applications

Метод	Путь	Скоуп	Описание
GET	/applications	applications:read	Список приложений
POST	/applications	applications:write	Создать приложение
GET	/applications/{id}	applications:read	Получить приложение
PATCH	/applications/{id}	applications:write	Обновить приложение
DELETE	/applications/{id}	applications:write	Удалить приложение
GET	/applications/{id}/roles	applications:read	Роли приложения
POST	/applications/{id}/roles	applications:write	Назначить роли
DELETE	/applications/{id}/roles/{roleId}	applications:write	Удалить роль

Создать приложение

curl -X POST https://your-domain.com/api/v1/{realmUUID}/applications \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SPA",
    "type": "spa",
    "redirect_uris": ["https://myapp.com/callback"]
  }'

{
  "data": {
    "id": "01HQ...",
    "name": "My SPA",
    "type": "spa",
    "client_id": "abc123",
    "redirect_uris": ["https://myapp.com/callback"],
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Назначить роли приложению

curl -X POST https://your-domain.com/api/v1/{realmUUID}/applications/{id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_ids": ["role-uuid-1"]}'

---

Roles API

Базовый путь: /api/v1/{realmUUID}/roles

Метод	Путь	Скоуп	Описание
GET	/roles	roles:read	Список ролей
POST	/roles	roles:write	Создать роль
GET	/roles/{id}	roles:read	Получить роль
PATCH	/roles/{id}	roles:write	Обновить роль
DELETE	/roles/{id}	roles:write	Удалить роль
GET	/roles/{id}/scopes	roles:read	Скоупы роли
POST	/roles/{id}/scopes	roles:write	Назначить скоупы
DELETE	/roles/{id}/scopes/{scopeId}	roles:write	Удалить скоуп

Создать роль

curl -X POST https://your-domain.com/api/v1/{realmUUID}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Can edit content"
  }'

Назначить скоупы роли

curl -X POST https://your-domain.com/api/v1/{realmUUID}/roles/{id}/scopes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"scope_ids": ["scope-uuid-1", "scope-uuid-2"]}'

---

Resources API

Базовый путь: /api/v1/{realmUUID}/resources

Метод	Путь	Скоуп	Описание
GET	/resources	resources:read	Список API-ресурсов
POST	/resources	resources:write	Создать ресурс
GET	/resources/{id}	resources:read	Получить ресурс
PATCH	/resources/{id}	resources:write	Обновить ресурс
DELETE	/resources/{id}	resources:write	Удалить ресурс
GET	/resources/{id}/scopes	resources:read	Скоупы ресурса
POST	/resources/{id}/scopes	resources:write	Добавить скоуп
PATCH	/resources/{id}/scopes/{scopeId}	resources:write	Обновить скоуп
DELETE	/resources/{id}/scopes/{scopeId}	resources:write	Удалить скоуп

Создать API-ресурс

curl -X POST https://your-domain.com/api/v1/{realmUUID}/resources \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "indicator": "https://api.myapp.com"
  }'

{
  "data": {
    "id": "01HQ...",
    "name": "My API",
    "indicator": "https://api.myapp.com",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Добавить скоуп к ресурсу

curl -X POST https://your-domain.com/api/v1/{realmUUID}/resources/{id}/scopes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read:posts",
    "description": "Read blog posts"
  }'

Обновить скоуп

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/resources/{id}/scopes/{scopeId} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"description": "Read all blog posts"}'