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

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

Проверяет 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",
    "phone": "+77011234567",
    "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 минут; одновременно активен только один код на пользователя — новый запрос инвалидирует предыдущий.

Письмо с кодом ставится в очередь отправки через Resend. При временной ошибке доставки выполняются повторные попытки. В отличие от обычной анти-перечислительной практики, эндпоинт намеренно отвечает 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
    }
  }
}

Ошибки