API Keys
API key разработчика — это учётные данные, которые ваш код предъявляет при каждом запросе. Keys создаются и управляются в панели администратора — не через сам API — и каждый key несёт среду, набор scopes и секрет, который показывается только один раз.
Где управляются keys
Управление keys находится в консоли разработчика панели по адресу /org/developer-api. Создание, перечисление, ротация и отзыв keys — это административные действия, выполняемые там с вашей обычной авторизованной сессией; они намеренно не входят в поверхность /v1, аутентифицируемую через cuk_ (утёкший key никогда не сможет создать или отозвать другой key). Консоль доступна на Starter и выше; организации на Trial не могут создавать keys.
Формат key
Секрет key имеет форму cuk_<env>_<random> — например:
cuk_live_M8s2k...<random>Он состоит из трёх частей:
| Часть | Значение |
|---|---|
cuk | Префикс бренда — каждый key Cuneiform Chat начинается с cuk_. |
<env> | Среда: live или test. |
<random> | Длинный, безопасный для URL случайный секрет. |
Среды
Каждый key создаётся для одной среды:
| Среда | Префикс | Применение |
|---|---|---|
live | cuk_live_ | Производственный трафик к вашим реальным данным. |
test | cuk_test_ | Разработка и интеграционное тестирование. |
Единоразовый показ
Полный секрет показывается ровно один раз — в момент создания или ротации key. После этого отображаются только префикс key (cuk_<env>_) и его последние четыре символа, чтобы можно было распознать key в списке, не имея возможности его восстановить.
Если секрет потерян, восстановить его нельзя — выполните ротацию key, чтобы получить новый (что отзывает старый секрет), либо отзовите его и создайте новый.
Scopes
Key получает подмножество из пяти scopes. Каждый scope открывает группу операций и дополнительно ограничен правами RBAC роли, создавшей key — key никогда не может предоставить больше, чем имеет его создатель в панели.
| Scope | Открывает | Потолок RBAC |
|---|---|---|
knowledge:read | Перечисление, поиск и получение документов, папок и tags. | Требует право чтения контента. |
knowledge:write | Загрузка, удаление и организация документов; создание/обновление/удаление папок и tags. | Требует права загрузки + обновления контента. |
agents:read | Перечисление и получение agents и их конфигурации. | Требует право чтения agent. |
agents:write | Создание и обновление agents; обновление конфигурации; удаление и восстановление. | Требует права создания + обновления agent (удаление/восстановление также требуют права удаления agent). |
agents:query | Запуск agent (POST /agents/{id}/query). | Требует право чтения agent. |
Предоставляйте key только нужные ему scopes. Запрос, вызывающий endpoint вне его scopes, отклоняется с 403 permission_error (invalid_scope).
Управление keys (в консоли)
Консоль разработчика по адресу /org/developer-api поддерживает:
- Создание — выберите среду и scopes; секрет показывается один раз.
- Перечисление — смотрите префикс каждого key, его последние четыре символа, scopes и статус (секрет больше никогда не показывается).
- Ротация — создайте новый секрет для key и отзовите предыдущий. Используйте это по регулярному графику или сразу, если key мог утечь.
- Отзыв — навсегда отключите key. Запросы, предъявляющие отозванный key, отклоняются с
401.
Для этих действий нет endpoint API — по замыслу они доступны только в панели.