Ключи

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

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

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

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

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

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

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

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

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

Префиксы #

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

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

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

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

Отзыв #

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

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

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

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

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

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

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

Гигиена #

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

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

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

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

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

Состояние #

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

Следить — в Обновлениях.