Авторизация¶

Токен можно получить двумя способами:

Способ	Когда	Методы
Логин и пароль	У школы нет своей системы учётных записей	«Вход по паролю»
Сервер-к-серверу	Учителя заведены в системе школы	«Пользователь из системы школы», «Токен пользователя из системы школы»

Способы можно совмещать: например, директор входит по паролю, а учителей заводит система школы.

Порядок входа сервер-к-серверу:

При входе человека в систему школы её бэкенд передаёт его актуальные данные методом «Пользователь из системы школы».
Бэкенд школы получает токен методом «Токен пользователя из системы школы» и передаёт его своему клиенту.
Через expires_in секунд или после ответа 401 клиент получает новый токен тем же путём.

Методы сервер-к-серверу закрыты ключом X-Api-Key; ключ хранится только на сервере школы. Ключей может быть несколько, чтобы менять их без простоя: администратор Wonk добавляет новый ключ, школа переключается на него, старый убирают.

Объект «Токен»¶

Параметр	Тип	Описание
`access_token`*	string	Токен доступа
`token_type`*	string	Всегда `bearer`
`expires_in`*	integer	Секунд до окончания токена

{"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer", "expires_in": 86400}

Объект «Пользователь»¶

Параметр	Тип	Описание
`id`*	uuid	id пользователя
`email`	string	Email в нижнем регистре; `null`, если пользователя завела система школы без email
`external_id`	string	id в системе школы; `null` у созданных директором
`first_name`*	string	Имя
`last_name`*	string	Фамилия
`role`*	string	`teacher` или `school_admin`
`is_active`*	boolean	`false` - учётная запись отключена
`created_at`*	datetime	Когда создана

{
  "id": "0b6f2c1e-6a0e-4c8b-9f7a-2d1c3b4a5e6f",
  "email": "teacher@school.kz",
  "external_id": null,
  "first_name": "Дана",
  "last_name": "Сеитова",
  "role": "teacher",
  "is_active": true,
  "created_at": "2026-11-10T10:00:00Z"
}

Вход по паролю¶

Выдаёт токен по email и паролю пользователя.

Запрос: POST {API_URL}/v1/auth/login

Авторизация не нужна, тело - application/x-www-form-urlencoded (форма OAuth2 password).

Параметр	Тип	Описание
`username`*	string	Email пользователя
`password`*	string	Пароль

Поля grant_type, scope, client_id, client_secret формы OAuth2 необязательны и не используются.

curl -X POST "$API_URL/v1/auth/login" -d username=teacher@school.kz -d password=secret123

Ответ 200: объект «Токен».

Код ошибки	Когда
`401`	Неверный email или пароль
`403`	Учётная запись отключена
`422`	Нет `username` или `password`

Текущий пользователь¶

Возвращает владельца токена.

Запрос: GET {API_URL}/v1/auth/me, авторизация - токен.

Ответ 200: объект «Пользователь».

Код ошибки	Когда
`401`	Нет токена, он недействителен или учётная запись отключена

Смена пароля¶

Меняет пароль владельца токена.

Запрос: POST {API_URL}/v1/auth/password, авторизация - токен.

Параметр	Тип	Описание
`current_password`*	string	Текущий пароль
`new_password`*	string	Новый пароль, 8-128 символов

{"current_password": "secret123", "new_password": "new-secret-123"}

Ответ 204 без тела.

Код ошибки	Когда
`400`	Неверный текущий пароль
`401`	Нет токена
`422`	Новый пароль короче 8 или длиннее 128 символов

Пользователь из системы школы¶

Создаёт человека из системы школы или заменяет его данные целиком. Запрос идемпотентный: его можно отправлять при каждом входе человека в систему школы.

Запрос: PUT {API_URL}/v1/integration/users/{external_id}

Авторизация - заголовок X-Api-Key с ключом школы.

Параметр	Тип	Описание
`external_id`*	string	В пути: id человека в системе школы, 1-255 символов; не переиспользуйте его для другого человека
`email`	string	Email; уникален среди всех учётных записей
`first_name`*	string	Имя, 1-255 символов
`last_name`*	string	Фамилия, 1-255 символов
`role`	string	`teacher` (по умолчанию) или `school_admin`
`is_active`	boolean	`true` по умолчанию; `false` отключает учётную запись

{"email": "teacher@school.kz", "first_name": "Дана", "last_name": "Сеитова", "role": "teacher", "is_active": true}

Ответ 200: объект «Пользователь» с заполненным external_id.

Код ошибки	Когда
`401`	Нет ключа или ключ неверный
`409`	Email занят другой учётной записью
`422`	Неверные поля
`503`	Вход сервер-к-серверу выключен: ключи не заданы

Токен пользователя из системы школы¶

Выдаёт токен человеку, ранее переданному методом «Пользователь из системы школы».

Запрос: POST {API_URL}/v1/integration/users/{external_id}/token, без тела.

Авторизация - заголовок X-Api-Key с ключом школы.

Ответ 200: объект «Токен».

Код ошибки	Когда
`401`	Нет ключа или ключ неверный
`403`	Учётная запись отключена
`404`	Человека с таким `external_id` нет
`503`	Вход сервер-к-серверу выключен: ключи не заданы