Аутентификация

Каждый запрос API для разработчиков должен нести API key разработчика. Публичной неаутентифицированной полосы нет — запрос без действительного key отклоняется с 401.

Предъявление вашего key

Отправьте секрет вашего key (cuk_<env>_<random>) одним из двух способов. Оба эквивалентны; используйте тот, что подходит вашему HTTP-клиенту.

Заголовок Authorization (рекомендуется)

Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx

Заголовок X-API-Key

X-API-Key: cuk_live_xxxxxxxxxxxxxxxx

Пример запроса для каждой формы:

# Bearer
curl https://cuneiform.chat/api/developer/v1/agents \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"
 
# X-API-Key
curl https://cuneiform.chat/api/developer/v1/agents \
  -H "X-API-Key: cuk_live_xxxxxxxxxxxxxxxx"

Во что сопоставляется key

Key привязан к двум вещам, обе из которых разрешаются автоматически при каждом запросе:

• Ваша организация. Key идентифицирует организацию, в которой он был создан. Каждый запрос ограничен этой организацией — id организации передавать не нужно, и достичь данных другой организации невозможно. Id ресурса, принадлежащего другой организации, сообщается как 404 (не найдено), а не 403.
• Его scopes. Key несёт фиксированный набор scopes, предоставленных при создании. Scope также ограничен правами RBAC роли, создавшей key — key никогда не может сделать больше, чем мог его создатель в панели. Запрос, которому нужен scope, отсутствующий у key, отклоняется с 403 permission_error.

Храните keys в секрете

Полный секрет key показывается ровно один раз — в момент создания или ротации. Относитесь к нему как к паролю:

• Отправляйте его только по HTTPS.
• Храните его в менеджере секретов или переменной окружения — никогда в системе контроля версий, клиентском коде или логах.
• Если key раскрыт, немедленно выполните ротацию или отзовите его.

Когда аутентификация не проходит

Отсутствующий, искажённый, отозванный или неизвестный key возвращает 401 со стандартным конвертом ошибки:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}

Корректно сформированный key, у которого нет scope (или соответствующего права) для операции, возвращает 403:

{
  "error": {
    "type": "permission_error",
    "code": "invalid_scope",
    "message": "This key does not have the required scope for this operation."
  }
}