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

Вход в систему

Проверяет email и пароль и создаёт управляемый сеанс устройства. Возвращает короткоживущий access JWT; браузеру refresh-токен передаётся только в защищённой HttpOnly cookie, а нативному приложению — в JSON. Поле subdomain указывает школу; пустое значение используется только для суперадмина платформы.

Тело запроса

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

curl -X POST https://api.edumentor.kz/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "teacher@acme.kz",
    "password": "super-secret",
    "subdomain": "acme",
    "installation_id": "web-installation-123",
    "device_platform": "web",
    "device_name": "Chrome · macOS",
    "os_name": "macOS",
    "browser_name": "Chrome"
  }'

Пример ответа

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "access_expires_at": "2026-08-30T12:15:00Z",
    "refresh_expires_at": "2026-11-28T12:00:00Z",
    "session_id": "745810eb-...",
    "auth_device_id": "2b9d59e5-...",
    "user": {
      "id": "8f3b1c2a-...",
      "email": "teacher@acme.kz",
      "role": "admin",
      "first_name": "Айгерим",
      "last_name": "Нурлан"
    }
  }
}

Ошибки

Продлить управляемый сеанс

Проверяет и атомарно ротирует refresh-токен, затем выдаёт новый короткоживущий access JWT. Браузер передаёт сохранённые non-secret session_id и auth_device_id, по которым сервер выбирает точную HttpOnly cookie; JavaScript не читает и не сохраняет сам refresh-секрет. Нативный клиент передаёт refresh_token в JSON и обязан безопасно сохранить новый токен из ответа.

Тело запроса

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

curl -X POST https://api.edumentor.kz/api/v1/auth/refresh   -H "Content-Type: application/json"   -H "X-Tenant-Subdomain: acme"   -b '<device-refresh-cookie>'   -d '{"session_id":"745810eb-...","auth_device_id":"2b9d59e5-..."}'

Пример ответа

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "access_expires_at": "2026-08-30T12:30:00Z",
    "refresh_expires_at": "2026-11-28T12:00:00Z",
    "session_id": "745810eb-...",
    "auth_device_id": "2b9d59e5-..."
  }
}

Ошибки

Завершить текущий сеанс

Отзывает текущую серверную сессию и очищает только выбранную браузерную refresh-cookie. Браузер обязан передать non-secret session_id и auth_device_id; сервер проверяет их связь с точной cookie до отзыва. Повторный вызов с уже завершённым подтверждённым семейством безопасен.

Тело запроса

Ошибки

Заменить устройство при входе

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

Тело запроса

Ошибки

Регистрация школы

Создаёт новую школу (тенант) в статусе pending, её первого администратора и пробный биллинг-период. Письмо подтверждения ставится в outbox атомарно с регистрацией. В актуальном режиме управляемых сессий после подтверждения нужен обычный login с метаданными установки.

Тело запроса

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

curl -X POST https://api.edumentor.kz/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_title": "Acme School",
    "tenant_slug": "acme",
    "email": "admin@acme.kz",
    "password": "super-secret",
    "first_name": "Айгерим",
    "last_name": "Нурлан"
  }'

Пример ответа

{
  "success": true,
  "data": {
    "verification_required": true,
    "email": "admin@acme.kz",
    "verification_expires_at": "2026-07-23T10:00:00Z"
  }
}

Ошибки

Подтвердить email владельца

Проверяет одноразовый токен из письма, отмечает email подтверждённым и переводит школу из pending в active. В актуальном режиме возвращает login_required=true: управляемый сеанс создаётся отдельным login. Поле token остаётся только для ограниченной legacy-совместимости.

Тело запроса

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

curl -X POST https://api.edumentor.kz/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{ "token": "<token-from-email>" }'

Пример ответа

{
  "success": true,
  "data": {
    "login_required": true,
    "tenant_subdomain": "acme",
    "user": { "id": "8f3b1c2a-...", "email": "admin@acme.kz", "role": "admin" }
  }
}

Ошибки

Повторить письмо подтверждения

Инвалидирует старую ссылку и ставит новую в outbox для pending-школы. Ответ всегда нейтральный и не раскрывает существование школы или email; действует минутный cooldown.

Тело запроса

Пример ответа

{
  "success": true,
  "data": { "message": "if the account is pending, a verification email has been queued" }
}

Запросить код сброса пароля

Создаёт 6-значный код подтверждения для сброса пароля. Поле subdomain указывает школу (для суперадмина — пусто). Код действует 15 минут; одновременно активен только один код на пользователя — новый запрос инвалидирует предыдущий.

⚠️ В текущей версии код не отправляется на email, а выводится в консоль сервера (интеграция с email-провайдером запланирована). В отличие от обычной анти-перечислительной практики, эндпоинт намеренно отвечает 404, если связки email + школа не существует.

Тело запроса

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

curl -X POST https://api.edumentor.kz/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "teacher@acme.kz", "subdomain": "acme" }'

Пример ответа

{
  "success": true,
  "data": { "message": "a confirmation code has been sent" }
}

Ошибки

Сбросить пароль по коду

Устанавливает новый пароль по действующему коду подтверждения. Код проверяется по связке email + школа. После 5 неверных попыток код блокируется (нужно запросить новый).

Тело запроса

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

curl -X POST https://api.edumentor.kz/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "teacher@acme.kz",
    "subdomain": "acme",
    "code": "048213",
    "new_password": "new-super-secret"
  }'

Пример ответа

{
  "success": true,
  "data": { "message": "password updated" }
}

Ошибки

Поиск школ по email

Возвращает список активных школ, в которые может войти указанный email. Используется экраном входа для автоподстановки школы. Авторизация не требуется.

Тело запроса

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

curl -X POST https://api.edumentor.kz/api/v1/auth/schools \
  -H "Content-Type: application/json" \
  -d '{ "email": "teacher@acme.kz", "scope": "admin" }'

Пример ответа

{
  "success": true,
  "data": [
    { "subdomain": "acme", "title": "Acme School", "role": "admin" }
  ]
}

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

Возвращает профиль авторизованного пользователя. Для тенант-пользователей дополнительно отдаёт состояние биллинга школы (plan_state, expires_at, days_remaining) для баннера пробного периода. Для суперадмина блок школы отсутствует.

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

curl https://api.edumentor.kz/api/v1/auth/me \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Subdomain: acme"

Пример ответа

{
  "success": true,
  "data": {
    "id": "8f3b1c2a-...",
    "email": "admin@acme.kz",
    "role": "admin",
    "first_name": "Айгерим",
    "last_name": "Нурлан",
    "tenant": {
      "plan_state": "trial",
      "expires_at": "2026-06-12T00:00:00Z",
      "days_remaining": 14
    }
  }
}

Ошибки