Вебхуки, SCIM и привязка устройств

Эта страница покрывает оставшиеся протокольные поверхности: привязку устройств (в API — pairing), корпоративную федерацию аутентификации (SAML / SCIM / OAuth), опциональные endpoints MCP-сервера и A2A, передачу медиа и сервисы Connect-RPC. Некоторые из них по умолчанию выключены и включаются явно.

Привязка устройств

Когда использовать: вы подключаете мобильное или настольное приложение AiHummer к своему инстансу. Мобильные и настольные клиенты подключаются через короткий обмен привязки (приложение iOS/macOS использует привязку только по QR).

Метод и путь	Назначение
`POST /v1/pairing/redeem`	Погасить код привязки и подготовить устройство
`POST /v1/pairing/device/validate`	Проверить уже привязанное устройство

curl https://your-aihummer.example/v1/pairing/redeem \
  -H "Content-Type: application/json" \
  -d '{ "code": "ABCD-EFGH" }'

Федерация аутентификации

Когда использовать: сотрудники должны входить через корпоративный провайдер удостоверений (IdP), а учётные записи — создаваться и отключаться автоматически. AiHummer интегрируется с корпоративными IdP как для входа, так и для автоматического создания пользователей.

SAML

Метод и путь	Назначение
`GET /saml/metadata`	Метаданные service-provider для вашего IdP
`POST /saml/acs`	Assertion Consumer Service (ответ SAML)
`GET /saml/login`	Инициировать вход через SAML

Автоматическое управление пользователями (SCIM)

SCIM 2.0 (System for Cross-domain Identity Management) позволяет вашему IdP автоматически создавать пользователей и управлять ими.

Метод и путь	Назначение
`.../scim/v2/Users`	Список / создание пользователей
`.../scim/v2/Users/{id}`	Чтение / обновление / удаление пользователя

SCIM-endpoints аутентифицируются SCIM bearer-токеном арендатора, который выпускается (и ротируется/отзывается) через POST /v1/admin/scim/token; IdP передаёт его в заголовке Authorization: Bearer. Токен показывается один раз при выпуске.

OAuth-токен

Метод и путь	Назначение
`POST /v1/oauth/token`	Endpoint выдачи OAuth-токена

MCP-сервер (публикация наружу)

AiHummer может публиковать собственные инструменты для MCP-клиентов, выступая как MCP-сервер. Когда использовать: внешние MCP-клиенты должны вызывать инструменты вашего инстанса. Это опционально и выключено, пока вы не установите AIHUMMER_MCP_PUBLISH=1.

Метод и путь	Назначение
`POST /v1/mcp`	Endpoint MCP-сервера (требует `AIHUMMER_MCP_PUBLISH=1`)

[!WARNING] Одного AIHUMMER_MCP_PUBLISH=1 недостаточно. Он открывает адрес, но список экспортируемых инструментов при этом пуст: tools/list возвращает пустой массив, а любой вызов отклоняется. Перечислите нужные инструменты точными именами через запятую в AIHUMMER_MCP_EXPORT_TOOLS — шаблоны и * не поддерживаются. Наружу разрешено отдавать только инструменты чтения: http_request, web_fetch, browser, code_exec и filesystem_read не экспортируются, даже если их перечислить.

Обе настройки задаются в Управление → Настройки или командой aihummer settings set, а не в gateway.env — для этих ключей окружение игнорируется. AIHUMMER_MCP_PUBLISH принимает ровно 1: true или on оставят адрес закрытым. Изменения вступают в силу после перезапуска шлюза.

Клиент обязан прислать ключ API с областью mcp в заголовке Authorization: Bearer …; без него ответ — 401.

[!NOTE] Публикация инструментов наружу отличается от потребления MCP-сервера как интеграции без разработки. Этот endpoint нужен, чтобы другие MCP-клиенты могли обращаться к AiHummer.

A2A (Agent-to-Agent)

AiHummer может предоставлять A2A-поверхность, чтобы другие агенты могли его обнаруживать и писать ему. Это тоже опционально через AIHUMMER_A2A_PUBLISH=1.

Метод и путь	Назначение
`GET /.well-known/agent.json`	Карточка агента A2A / документ discovery
`POST /a2a/message`	Приём A2A-сообщения (требует `AIHUMMER_A2A_PUBLISH=1`)

Медиа

Крупные медиа (аудио, изображения, файлы) загружаются и скачиваются через выделенные endpoints, а не встраиваются в JSON-тела.

Метод и путь	Назначение
`PUT /v1/media/{id}/content`	Загрузить байты медиа-объекта
`GET /v1/files/{id}`	Скачать сохранённый файл

[!TIP] Установите AIHUMMER_BLOB_DIR, чтобы включить сервис медиа/файлов, и AIHUMMER_MEDIA_TOKEN_SECRET, чтобы подписанные URL для скачивания оставались валидными после перезапусков.

Сервисы Connect-RPC

Для типизированных потоковых клиентов AiHummer также предоставляет сервисы Connect-RPC поверх HTTP (поддерживается server-streaming):

Сервис	Область
`aihummer.health.v1`	Проверки работоспособности
`aihummer.event.v1`	Поток событий
`aihummer.conversation.v1`	Беседы
`aihummer.push.v1`	Доставка push
`aihummer.media.v1`	Передача медиа
`aihummer.turn.v1`	Обработка запроса (turn)

Куда дальше

Доставка сообщений в AiHummer: Входящие и интеграционные триггеры.
Переключение этих и других поверхностей: Переменные окружения.
Управление инстансом: Справочник CLI.