Public

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

Вход, регистрация школы, сброс пароля по коду, автоопределение школ по email и профиль текущего пользователя. Эти эндпоинты не требуют авторизации (кроме /me).

POST/api/v1/auth/loginВход в систему
POST/api/v1/auth/registerРегистрация школы
POST/api/v1/auth/forgot-passwordЗапросить код сброса пароля
POST/api/v1/auth/reset-passwordСбросить пароль по коду
POST/api/v1/auth/schoolsПоиск школ по email
GET/api/v1/auth/meТекущий пользователь

POST/api/v1/auth/login

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

Public Без авторизации

Проверяет email и пароль и возвращает JWT-токен. Поле subdomain опционально: укажите его для входа в кабинет конкретной школы; оставьте пустым для входа суперадмина платформы.

Тело запроса

Параметр	Тип	Описание
`email`обяз.	`string`	Email пользователя.
`password`обяз.	`string`	Пароль.
`subdomain`опц.	`string`	Субдомен школы (только латиница и цифры). Пусто — вход суперадмина (`tenant_id IS NULL`).Пример: `acme`

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

cURL

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"
  }'

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

200 OK · application/json

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "8f3b1c2a-...",
      "email": "teacher@acme.kz",
      "role": "admin",
      "first_name": "Айгерим",
      "last_name": "Нурлан"
    }
  }
}

Ошибки

Код	error	Когда
400	`invalid credentials`	Неверный email или пароль (обобщённое сообщение — без раскрытия деталей).
423	`too many attempts, try again later`	Сработала защита от перебора — слишком много попыток входа.

POST/api/v1/auth/register

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

Public Без авторизации

Создаёт новую школу (тенант), её первого администратора и пробный биллинг-период. Сразу засевается демо-контент (курс + тест), чтобы кабинет не был пустым.

Тело запроса

Параметр	Тип	Описание
`tenant_title`обяз.	`string`	Название школы (2–255 символов).
`tenant_slug`обяз.	`string`	Уникальный slug школы (латиница/цифры, 2–100).Пример: `acme`
`tenant_subdomain`опц.	`string`	Субдомен. Если не задан — берётся из slug.Пример: `acme`
`email`обяз.	`string`	Email администратора.
`password`обяз.	`string`	Пароль (минимум 8 символов).
`first_name`обяз.	`string`	Имя администратора.
`last_name`обяз.	`string`	Фамилия администратора.

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

cURL

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": "Нурлан"
  }'

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

200 OK · application/json

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

Ошибки

Код	error	Когда
400	`duplicate key`	Школа с таким slug/субдоменом или пользователь с таким email уже существует.

POST/api/v1/auth/forgot-password

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

Public Без авторизации

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

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

Тело запроса

Параметр	Тип	Описание
`email`обяз.	`string`	Email пользователя.
`subdomain`опц.	`string`	Субдомен школы (латиница/цифры). Пусто — суперадмин.Пример: `acme`

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

cURL

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

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

200 OK · application/json

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

Ошибки

Код	error	Когда
400	`validation error`	Некорректный email или невалидный субдомен.
404	`no account with this email and school`	Нет аккаунта с такой связкой email + школа.

POST/api/v1/auth/reset-password

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

Public Без авторизации

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

Тело запроса

Параметр	Тип	Описание
`email`обяз.	`string`	Email пользователя.
`subdomain`опц.	`string`	Субдомен школы (латиница/цифры). Пусто — суперадмин.Пример: `acme`
`code`обяз.	`string`	6-значный код подтверждения (только цифры).Пример: `048213`
`new_password`обяз.	`string`	Новый пароль (минимум 8 символов).

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

cURL

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"
  }'

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

200 OK · application/json

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

Ошибки

Код	error	Когда
400	`invalid or expired confirmation code`	Код неверный, просрочен (TTL 15 мин) или уже использован.
423	`too many attempts, request a new code`	Исчерпан лимит из 5 попыток ввода кода — запросите новый.

POST/api/v1/auth/schools

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

Public Без авторизации

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

Тело запроса

Параметр	Тип	Описание
`email`обяз.	`string`	Email для поиска.
`scope`опц.	`string`	Фильтр по роли: `admin` — только кабинеты (админ/куратор), `student` — только школы, где email является учеником. Пусто — любая роль.Пример: `admin`

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

cURL

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

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

200 OK · application/json

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

GET/api/v1/auth/me

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

PublicTenantSuperadmin JWT

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

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

cURL

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

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

200 OK · application/json

{
  "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
    }
  }
}

Ошибки

Код	error	Когда
401	`unauthorized`	Токен отсутствует, истёк или недействителен.

НазадЖизненный цикл работ по заданиям Далее Тенанты и брендинг