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

Схемы заголовков для доступа к API от имени тенанта, конечного пользователя и в режиме прокси.

Типы учетных данных

Схема	Заголовки	От чьего имени
API-ключ тенанта	`X-API-Key: tk_…` (либо `Authorization: Bearer tk_…`)	Ваш тенант
Конечный пользователь в режиме прокси	`X-API-Key: tk_…` + `X-End-User: <your-user-id>`	Конкретный конечный пользователь, которого удостоверяет ваш бэкенд
Конечный пользователь платформы	`Authorization: Bearer <jwt>`	Конечный пользователь, вошедший через `/auth/login` или OAuth

Необязательный заголовок X-Space-Id выбирает конкретное пространство; без него используется пространство пользователя по умолчанию.

Любая из схем разрешается в принципал (тенант · пользователь · пространство), после чего сессия базы данных ограничивается этой идентичностью средствами row-level security в Postgres — то есть изоляция обеспечивается ниже уровня API, а не кодом приложения.

Что выбрать

Интеграция сервер — сервер (диалогами управляет ваш продукт): используйте режим прокси. Ключ тенанта хранится на бэкенде, а личность конечного пользователя передается в каждом запросе — пользователи ключ не видят.
Собственные клиентские приложения, где пользователи входят непосредственно в платформу: используйте JWT конечного пользователя.
Административная автоматизация (документы, агенты, расход): используйте обычный ключ тенанта и управляющие эндпоинты.

API-ключ тенанта — серверный секрет. Никогда не размещайте его в браузерном коде или мобильных приложениях: для браузера предназначен встраиваемый виджет, который авторизуется через share-токены.

Пример работы в режиме прокси

curl https://chat.agent4.io/chat \
  -H "X-API-Key: tk_live_…" \
  -H "X-End-User: crm-user-8841" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Какие документы нужны для рефинансирования?" }'

Идентификатором конечного пользователя может быть любой стабильный идентификатор из вашей системы. При первом обращении платформа создает пользователя и его пространство по умолчанию, а затем привязывает к нему всю историю, память и документы.

Ошибки

Код	Значение
`401`	Учетные данные отсутствуют или недействительны
`403`	Идентичность верна, но доступа к запрошенному пространству или агенту нет
`429`	Месячная квота токенов исчерпана

Интерфейс агента (Agent-to-Agent)

Chat API