StudyИнструкция
Войти

Enterprise API: ключ и авторизация

Как получить ключ школы, куда слать запросы и чем отличаются два уровня доступа.

Enterprise API нужен, чтобы ваш сайт, CRM или бот работали с 1Study напрямую: выдавали ученикам доступ к курсам, получали список курсов, показывали ученику его прогресс. Всё, что доступно по ключу, ограничено вашей школой — чужие школы через него не видны.

Как получить ключ

Ключ школы выдаёт команда 1Study: напишите в поддержку, и мы пришлём его ответственному за интеграцию. Кнопки самостоятельной генерации в кабинете сейчас нет. Ключ начинается с ent_ и не меняется, пока вы не попросите его заменить.

Внимание
Ключ равен доступу ко всей базе учеников школы: телефоны, имена, прогресс. Держите его только на своём сервере, в переменных окружения. Если вставить ключ в код сайта или мобильного приложения, его увидит любой посетитель. При утечке сразу напишите нам, мы заменим ключ.

Адрес API

Базовый адрес: https://api.1app.kz. Тот же API отвечает и на домене вашей школы, например https://вашашкола.one — можно использовать любой из них.

Два уровня доступа

  • Только ключ школы — заголовок X-API-Key. Этого достаточно для действий от имени школы: выдать доступ к курсу, получить список курсов, найти ученика по телефону.
  • Ключ школы плюс токен ученика — заголовки X-API-Key и Authorization: Bearer. Нужен там, где данные принадлежат конкретному ученику: его записи, уроки, задания, тесты, уведомления.

Как получить токен ученика

  1. 1
    По паролю
    POST /api/enterprise/v2/auth/login, в теле phone и password.
  2. 2
    По коду из СМС
    POST /api/enterprise/v2/auth/send-otp с телефоном, затем POST /api/enterprise/v2/auth/verify с телефоном и кодом.

Если ученик забыл пароль

В приложении на экране входа есть «Забыли пароль»: ученик вводит номер, получает код и задаёт новый пароль. Отдельного метода сброса в Enterprise API нет, и это осознанно: пароль меняет только сам ученик, подтвердив номер кодом.

Если нужно сделать такую же форму у себя на сайте, со своего сервера можно вызвать публичные методы: POST /api/auth/send-otp с номером, затем POST /api/auth/verify-reset-otp с номером и кодом, затем POST /api/auth/reset-password с номером и новым паролем. Ключ школы там не нужен, но и из браузера напрямую они не вызываются, только с вашего сервера.

Совет
Для рассылки по старой базе сброс обычно не нужен. Тем, кто ни разу не заходил, пароль ставится в момент выдачи доступа и приходит вам в ответе. Тем, у кого пароль уже есть, достаточно напомнить про «Забыли пароль» в приложении.

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

curl -X GET "https://api.1app.kz/api/enterprise/v2/lms/courses" \
  -H "X-API-Key: ent_ваш_ключ"

Ошибки

  • 401 UNAUTHORIZED — ключ не передан, неверен или не начинается с ent_.
  • 400 VALIDATION_ERROR — не хватает поля в теле запроса или неверный формат.
  • 404 NOT_FOUND — объект не найден или принадлежит другой школе.
  • 429 — слишком часто, ограничение стоит на методах входа ученика.
Подсказка
Ответы приходят в виде JSON с полем success. При успехе данные лежат в data, при ошибке в error есть message и code.