Webhooks, SCIM & Pairing

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

This page covers the remaining protocol surfaces: **device pairing**, enterprise **auth federation** (SAML / SCIM / OAuth), the opt-in **MCP server** and **A2A** endpoints, **media** transfer, and the **Connect-RPC** services. Several of these are off by default and must be enabled explicitly. ## Device pairing Mobile and desktop clients join an instance through a short pairing exchange (the iOS/macOS app uses QR-only pairing). | Method & path | Purpose | |---|---| | `POST /v1/pairing/redeem` | Redeem a pairing code and provision the device | | `POST /v1/pairing/device/validate` | Validate an already-paired device | ```bash curl https://your-aihummer.example/v1/pairing/redeem \ -H "Content-Type: application/json" \ -d '{ "code": "ABCD-EFGH" }' ``` ## Auth federation AiHummer integrates with enterprise identity providers for both login and user provisioning. ### SAML | Method & path | Purpose | |---|---| | `GET /saml/metadata` | Service-provider metadata for your IdP | | `POST /saml/acs` | Assertion Consumer Service (SAML response) | | `GET /saml/login` | Initiate SAML login | ### SCIM provisioning System for Cross-domain Identity Management (SCIM 2.0) lets your IdP create and manage users automatically. | Method & path | Purpose | |---|---| | `.../scim/v2/Users` | List / create users | | `.../scim/v2/Users/{id}` | Read / update / delete a user | ### OAuth token | Method & path | Purpose | |---|---| | `POST /v1/oauth/token` | OAuth token endpoint | ## MCP server (publish outward) AiHummer can publish its own tools to MCP clients by acting as an **MCP server**. This is **opt-in** and disabled unless you set `AIHUMMER_MCP_PUBLISH=1`. | Method & path | Purpose | |---|---| | `POST /v1/mcp` | MCP server endpoint (requires `AIHUMMER_MCP_PUBLISH=1`) | > [!NOTE] > Publishing tools outward is distinct from *consuming* an MCP server as a > zero-code integration. This endpoint is for letting other MCP clients call into > AiHummer. ## A2A (Agent-to-Agent) AiHummer can expose an A2A surface so other agents can discover and message it. This is also **opt-in** via `AIHUMMER_A2A_PUBLISH=1`. | Method & path | Purpose | |---|---| | `GET /.well-known/agent.json` | A2A agent card / discovery document | | `POST /a2a/message` | Receive an A2A message (requires `AIHUMMER_A2A_PUBLISH=1`) | ## Media Large media (audio, images, files) is uploaded and fetched through dedicated endpoints rather than embedded in JSON bodies. | Method & path | Purpose | |---|---| | `PUT /v1/media/{id}/content` | Upload the bytes for a media object | | `GET /v1/files/{id}` | Download a stored file | > [!TIP] > Set `AIHUMMER_BLOB_DIR` to enable the media/file service, and > `AIHUMMER_MEDIA_TOKEN_SECRET` so signed download URLs stay valid across > restarts. ## Connect-RPC services For typed, streaming clients AiHummer also exposes **Connect-RPC** services over HTTP (server-streaming is supported): | Service | Area | |---|---| | `aihummer.health.v1` | Health checks | | `aihummer.event.v1` | Event stream | | `aihummer.conversation.v1` | Conversations | | `aihummer.push.v1` | Push delivery | | `aihummer.media.v1` | Media transfer | | `aihummer.turn.v1` | Turn execution | ## Where to next - Push messages into AiHummer: [Inbound & integration triggers](/en/v1.0/api/inbound-triggers). - Toggle these surfaces and more: [Environment variables](/en/v1.0/reference/env-vars). - Operate the instance: [CLI reference](/en/v1.0/reference/cli).