AiHummer
English▾
Log in
v1.0.x▾
v1.0.xstable
{ }Swagger
API/Webhooks, SCIM & Pairing

Webhooks, SCIM & Pairing

v1.0.x · updated 2026-07-05

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 
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

The SCIM endpoints authenticate with a per-tenant SCIM bearer token, issued (and rotated/revoked) at POST /v1/admin/scim/token; the IdP sends it in an Authorization: Bearer header. The token is shown once at issue time.

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