API - Exode — Продуктовая документация

Платформа предоставляет GraphQL API для интеграции школы с внешними системами. Через API можно программно получать и изменять данные школы в рамках выданных прав. Доступ к API выдаётся через сервисного пользователя с персональным токеном (API-ключом). Управление ключами находится в разделе Управление → Школа → API-ключи (/manage/school/api-keys). Список API-ключей школы

API-ключи

API-ключ — это токен, привязанный к сервисному пользователю школы. У каждого ключа есть набор прав (permissions), которые определяют, какие операции доступны через API. Ключ можно включать и выключать (active), ограничивать права и перевыпускать (ротация). В списке для каждого ключа показаны: email сервисного пользователя, превью токена (apiTokenPreview), дата выпуска ключа, статус и количество прав.

Генерация ключа

Откройте раздел «API-ключи»

Перейдите в управление школой и выберите «API-ключи». Нажмите Создать API-ключ.

Выпустите ключ

Нажмите Выпустить API-ключ — платформа создаст сервисного пользователя и сгенерирует токен.

Сохраните токен

Токен показывается полностью только один раз — сразу после выпуска. Скопируйте его и сохраните в надёжном месте.

Настройте права

Откройте ключ и отметьте нужные права (permissions), сгруппированные по модулям. Сохраните изменения.

Форма выпуска API-ключа и настройки прав

Полный токен отображается только один раз при выпуске. Если вы его потеряли — используйте ротацию, чтобы выпустить новый (старый токен при этом станет недействительным).

Ротация ключа

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

Ротация немедленно инвалидирует старый токен. Обновите токен во всех интеграциях, которые им пользуются, иначе их запросы начнут получать ошибку авторизации.

Эндпоинт и авторизация

Все запросы отправляются на GraphQL-эндпоинт платформы. Его адрес задаётся переменной окружения REACT_APP_GRAPHQL_CSR_URL (в продакшене — GraphQL-эндпоинт вашей инсталляции, например https://<домен>/graphql). Авторизация выполняется по Bearer-токену в заголовке Authorization. Кроме того, запрос идентифицирует школу по заголовку School-Id.

Заголовок	Значение	Назначение
`Authorization`	`Bearer <токен>`	API-ключ сервисного пользователя
`School-Id`	ID школы	Идентификация школы для запроса

Токен API-ключа даёт доступ к данным школы в объёме выданных прав. Храните его только на своём сервере, не размещайте в клиентском коде и в кастомном коде школы — он виден всем посетителям.

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

Ниже — пример вызова GraphQL API через curl. Запрос и переменные передаются в теле POST-запроса, токен — в заголовке Authorization.

curl -X POST 'https://<домен>/graphql' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ваш-токен>' \
  -H 'School-Id: 42' \
  -d '{
    "query": "query WebhookEndpointFindMany($list: ListInput!, $filter: FilterEndpointWebhookInput!) { webhookEndpointFindMany(list: $list, filter: $filter) { count items { id url active events } } }",
    "variables": { "list": { "skip": 0, "take": 20 }, "filter": {} }
  }'

Сам GraphQL-запрос выглядит так:

query WebhookEndpointFindMany(
    $list: ListInput!,
    $filter: FilterEndpointWebhookInput!
) {
    webhookEndpointFindMany(
        list: $list,
        filter: $filter
    ) {
        count
        items {
            id
            url
            active
            events
        }
    }
}

Актуальный список доступных операций, типов и полей определяется GraphQL-схемой платформы (schema.gql). Набор реально доступных вам операций ограничен правами (permissions), выданными конкретному API-ключу.

Связанные разделы

Вебхуки

Получайте уведомления о событиях школы без постоянного опроса API.

Техническая документация

Как устроены фронтенд, платформы и работа с GraphQL.

​API-ключи

​Генерация ключа

​Ротация ключа

​Эндпоинт и авторизация

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

​Связанные разделы

Вебхуки

Техническая документация

API-ключи

Генерация ключа

Ротация ключа

Эндпоинт и авторизация

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

Связанные разделы