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

Все запросы к REST API аутентифицируются одним и тем же способом — API-ключом организации.

Заголовок авторизации

Authorization: Bearer <api-key>

Ключ передаётся в каждом запросе. Без него или с неверным ключом API отвечает 401 unauthorized.

curl https://api.cosai.pro/v1/agents \
  -H "Authorization: Bearer cosai_sk_…"

Как получить ключ

Ключ выдаётся при подключении организации к платформе (см. Организация и API-ключи). Тот же ключ, которым вы входите в консоль, подходит и для прямых вызовов API.

Области доступа (scope)

Ключи различаются возможностями:

• ключ полного доступа — весь REST API: создание баз знаний, агентов, запуск eval, публикация;
• ключ chat:widget — только диалог с конкретным опубликованным агентом (POST /agents/:id/chat), и только с доменов из allowlist ключа (см. Домен-allowlist). Такой ключ предназначен для встраивания в клиентский код сайта и не даёт доступа к остальным методам API.

Безопасность

• Не встраивайте ключ полного доступа в код, доступный в браузере — используйте его только на своём сервере или в консоли.
• Для клиентских интеграций (сайт, мобильное приложение) используйте только ограниченный ключ chat:widget.
• Платформа хранит только хеш ключа, поэтому при подозрении на утечку ключ нужно заменить — обратитесь к команде, обслуживающей вашу организацию на платформе.

CORS

Для запросов из браузера (например, собственный фронтенд, а не готовый виджет) API отражает заголовок Origin в ответе, поддерживая GET, POST, PATCH, DELETE, OPTIONS. Для ключей со scope chat:widget при этом действует ограничение по allowlist доменов — запрос из недоверенного домена будет отклонён на уровне аутентификации, даже если CORS-заголовки присутствуют.