# Ключи

Ключ заводит школа, в своих настройках. Не по заявке нам и не по анкете: коробка
стоит на вашем сервере, мы к ней не касаемся, и требовать обращения ради ключа было
бы странно.

У GetCourse ключ разработчика выдаётся по анкете, а документация к нему закрыта
в `robots.txt` — это первое, обо что спотыкается интегратор, и повторять это мы
не будем.

## Где заводится

Настройки школы → API. Там же виден **базовый адрес именно этой установки**
и готовый пример запроса с подставленным ключом — чтобы проверить копированием
в терминал, не собирая адрес по кускам из документации.

## Что задаётся при создании

| Поле | Обязательно | Зачем |
|---|---|---|
| **Название** | да | «Интеграция с amoCRM». Через полгода это единственное, по чему ключ опознают |
| **Права** | да | См. ниже — те же, что у роли человека |
| **Срок действия** | нет | Ключ на время миграции стоит завести с датой окончания |
| **Разрешённые адреса** | нет | Список IP, с которых ключ принимается |

Про название: оно не для порядка. Экран со списком ключей — то место, где через
полгода решают, можно ли отозвать вот этот. Ключ с названием «тест» отозвать
боятся, потому что неизвестно, что отвалится.

## Значение показывается один раз

При создании — и больше никогда. В базе лежит только хеш.

Потеряли — заведите новый и отзовите старый. Это не строгость ради строгости:
хранить ключ в открытом виде значит отдать все ключи школы вместе с одной копией
базы.

## Префиксы

| Префикс | Что это |
|---|---|
| `lms_live_` | Боевой ключ |
| `lms_test_` | Ключ [песочницы](/api/sandbox/) |

Префикс информативен намеренно: случайно закоммиченный ключ такого вида
опознаётся сканером секретов и отзывается **до** того, как им кто-нибудь
воспользуется. Ключ вида `a8f3c1e9…` не опознаётся ничем.

## Что видно в списке

Название, кто создал, когда создан, **когда использовался последний раз**,
с каких адресов, сколько запросов за сутки, состояние.

Две колонки здесь важнее остальных. «Когда использовался последний раз» отвечает
на вопрос «этот ключ ещё нужен» — ключ, не использовавшийся полгода, отзывается
без сожалений. «С каких адресов» отвечает на вопрос «его точно не увели».

## Отзыв

Одной кнопкой, немедленный. Не «через час», не «после следующего запроса» —
следующий же запрос получает `401`.

Отзыв ключа не отменяет того, что этим ключом уже сделано: выданные доступы
остаются выданными, отправленные сообщения — отправленными. Это то же правило,
что и с людьми: **отзыв прекращает создание нового, а не работу созданного**.
Разбирать последствия придётся отдельно, зато отзыв не ломает школе работу
посреди дня.

## Права ключа — те же, что у роли

**Второго перечня прав в продукте нет.** Ключ — такой же субъект прав, как человек:
ему назначается роль или явный набор тех же самых прав, и проверяет их та же
функция.

Причина простая. Два списка прав — это два источника правды на один вопрос
«кому что можно». Они разойдутся, вопрос только в том, через сколько заходов,
и разойдутся **молча**: право закроют на экране и забудут закрыть в API.

Отсюда бесплатно получается то, чего у платформ обычно нет: **сужение ключа
до конкретных курсов**. Ключ лендинга умеет выдавать доступ только к тому курсу,
который на этом лендинге продаётся. У GetCourse ограничить сотрудника одним
курсом можно только назначив его преподавателем, а всё остальное — на весь
аккаунт целиком.

Отдельно про агентов: **ключ для ИИ-агента по умолчанию создаётся только
на чтение**, права на запись выдаются явно. Почему — на странице
[Ключ с узкими правами](/agents/keys/).

## Гигиена

Четыре правила, каждое из которых написано по чужой беде.

**Ключ на интеграцию, а не на человека.** Уволился сотрудник — отзывается его
доступ, а не десять интеграций, которые он когда-то настроил.

**Отдельный ключ на каждую интеграцию.** Один ключ на всё нельзя отозвать
выборочно: придётся останавливать всё сразу и заводить заново.

**Ключ не в репозитории.** Даже в приватном: приватный репозиторий однажды
станет публичным, или его склонирует подрядчик.

**Список адресов там, где адрес постоянный.** У сервера интеграции он обычно
постоянный, и это самая дешёвая защита из существующих: увезённый ключ
не сработает с чужой машины.

## Состояние

**Реестра ключей в продукте ещё нет** — он появится вместе с реализацией API.
Правила выше приняты и не изменятся; экрана, на котором ключ заводится, пока
не существует.

Следить — в [Обновлениях](/changelog/).