> ## Documentation Index
> Fetch the complete documentation index at: https://faq.exode.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> GraphQL API школы: генерация API-ключей, авторизация по Bearer-токену, эндпоинт и пример запроса

Платформа предоставляет GraphQL API для интеграции школы с внешними системами. Через API можно
программно получать и изменять данные школы в рамках выданных прав. Доступ к API выдаётся через
**сервисного пользователя** с персональным токеном (API-ключом).

Управление ключами находится в разделе **Управление → Школа → API-ключи** (`/manage/school/api-keys`).

<img src="https://mintlify.s3.us-west-1.amazonaws.com/exode-faq/images/online-schools/developers/api-keys-list.png" alt="Список API-ключей школы" />

## API-ключи

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

В списке для каждого ключа показаны: email сервисного пользователя, превью токена (`apiTokenPreview`),
дата выпуска ключа, статус и количество прав.

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

<Steps>
  <Step title="Откройте раздел «API-ключи»">
    Перейдите в управление школой и выберите «API-ключи». Нажмите **Создать API-ключ**.
  </Step>

  <Step title="Выпустите ключ">
    Нажмите **Выпустить API-ключ** — платформа создаст сервисного пользователя и сгенерирует токен.
  </Step>

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

  <Step title="Настройте права">
    Откройте ключ и отметьте нужные права (`permissions`), сгруппированные по модулям. Сохраните изменения.
  </Step>
</Steps>

<img src="https://mintlify.s3.us-west-1.amazonaws.com/exode-faq/images/online-schools/developers/api-key-form.png" alt="Форма выпуска API-ключа и настройки прав" />

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

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

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

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

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

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

Авторизация выполняется по Bearer-токену в заголовке `Authorization`. Кроме того, запрос идентифицирует
школу по заголовку `School-Id`.

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

<Warning>
  Токен API-ключа даёт доступ к данным школы в объёме выданных прав. Храните его только на своём сервере,
  не размещайте в клиентском коде и в [кастомном коде](/online-schools/developers/custom-code) школы —
  он виден всем посетителям.
</Warning>

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

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

```bash theme={null}
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-запрос выглядит так:

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

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

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

<Card title="Вебхуки" icon="webhook" href="/online-schools/developers/webhooks">
  Получайте уведомления о событиях школы без постоянного опроса API.
</Card>

<Card title="Техническая документация" icon="code" href="/online-schools/developers/technical-overview">
  Как устроены фронтенд, платформы и работа с GraphQL.
</Card>