Webhooks, SCIM y Emparejamiento

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

Esta página cubre las superficies de protocolo restantes: **emparejamiento de dispositivos**, empresa **federación de autenticación** (SAML / SCIM / OAuth), la opción de participación **servidor MCP** y **A2A** puntos finales, **media** transferir, y el **Conectar-RPC** servicios. Varios de estos están desactivados por defecto y deben ser habilitados explícitamente. ## Emparejamiento de dispositivos Los clientes móviles y de escritorio se unen a una instancia a través de un intercambio de emparejamiento corto (la aplicación para iOS/macOS usa emparejamiento solo con código QR). | Método y ruta | Propósito | |---|---| | `POST /v1/pairing/redeem` | Canjear un código de emparejamiento y aprovisionar el dispositivo | | `POST /v1/pairing/device/validate` | Validar un dispositivo ya emparejado | ```bash curl https://your-aihummer.example/v1/pairing/redeem \ -H "Content-Type: application/json" \ -d '{ "code": "ABCD-EFGH" }' ``` ## Federación de autenticación AiHummer se integra con los proveedores de identidad empresarial tanto para el inicio de sesión como para el aprovisionamiento de usuarios. ### SAML | Método y ruta | Propósito | |---|---| | `GET /saml/metadata` | Metadatos del proveedor de servicios para su IdP | | `POST /saml/acs` | Servicio de Consumidor de Aserciones (respuesta SAML) | | `GET /saml/login` | Iniciar sesión SAML | ### Aprovisionamiento SCIM El Sistema para la Gestión de Identidad Interdominios (SCIM 2.0) permite que su IdP cree y gestione usuarios automáticamente. | Método y ruta | Propósito | |---|---| | `.../scim/v2/Users` | Listar / crear usuarios | | `.../scim/v2/Users/{id}` | Leer / actualizar / eliminar un usuario | Los endpoints SCIM se autentican con un **token portador SCIM por inquilino**, emitido (y rotado/revocado) en `POST /v1/admin/scim/token`; el IdP lo envía en un `Authorization: Bearer` encabezado. El token se muestra solo una vez en el momento de emisión. ### Token OAuth | Método y ruta | Propósito | |---|---| | `POST /v1/oauth/token` | Punto de acceso de token OAuth | ## Servidor MCP (publicar hacia afuera) AiHummer puede publicar sus propias herramientas a los clientes de MCP actuando como un **servidor MCP**. Esto es **optar por participar** y desactivado a menos que configures `AIHUMMER_MCP_PUBLISH=1`. | Método y ruta | Propósito | |---|---| | `POST /v1/mcp` | Punto de acceso del servidor MCP (requiere `AIHUMMER_MCP_PUBLISH=1`) | > [!WARNING] > **`AIHUMMER_MCP_PUBLISH=1` por sí solo no basta.** Abre la dirección, pero la > lista de exportación está vacía: `tools/list` devuelve un array vacío y toda > llamada se rechaza. Enumere las herramientas por **nombre exacto, separadas > por comas**, en `AIHUMMER_MCP_EXPORT_TOOLS`; no se admiten patrones ni `*`. > Solo pueden publicarse herramientas de **lectura**: `http_request`, > `web_fetch`, `browser`, `code_exec` y `filesystem_read` nunca se exportan, > aunque las nombre. > > Ambos ajustes se definen en **Gestión → Ajustes** o con > `aihummer settings set`, no en `gateway.env`: el entorno se ignora para estas > claves. `AIHUMMER_MCP_PUBLISH` acepta exactamente `1`: `true` u `on` dejan > la dirección cerrada. Los cambios se aplican tras reiniciar la pasarela. > > El cliente debe enviar una clave de API con el ámbito `mcp` en la cabecera > `Authorization: Bearer …`; sin ella la respuesta es 401. > [!NOTE] > Publicar herramientas hacia el exterior es distinto de *consumir* un servidor MCP como un > integración sin código. Este endpoint es para permitir que otros clientes de MCP llamen > AiHummer. ## A2A (De agente a agente) AiHummer puede exponer una superficie A2A para que otros agentes puedan descubrirla y enviarle mensajes. Esto también **optar por participar** vía `AIHUMMER_A2A_PUBLISH=1`. | Método y ruta | Propósito | |---|---| | `GET /.well-known/agent.json` | Tarjeta de agente A2A / documento de descubrimiento | | `POST /a2a/message` | Recibir un mensaje A2A (requiere `AIHUMMER_A2A_PUBLISH=1`) | ## Medios Los medios grandes (audio, imágenes, archivos) se cargan y se obtienen a través de endpoints dedicados en lugar de estar incrustados en cuerpos JSON. | Método y ruta | Propósito | |---|---| | `PUT /v1/media/{id}/content` | Sube los bytes de un objeto de medios | | `GET /v1/files/{id}` | Descargar un archivo almacenado | > [!TIP] > Conjunto `AIHUMMER_BLOB_DIR` para habilitar el servicio de medios/archivos, y > `AIHUMMER_MEDIA_TOKEN_SECRET` así que las URL de descarga firmadas permanecen válidas a lo largo de > reinicios. ## Servicios Connect-RPC Para clientes tipeados y en transmisión, AiHummer también expone **Conectar-RPC** servicios sobre HTTP (se admite la transmisión desde el servidor): | Servicio | Área | |---|---| | `aihummer.health.v1` | Controles de salud | | `aihummer.event.v1` | Flujo de eventos | | `aihummer.conversation.v1` | Conversaciones | | `aihummer.push.v1` | Entrega push | | `aihummer.media.v1` | Transferencia de medios | | `aihummer.turn.v1` | Ejecución de turno | ## ¿A dónde vamos ahora? - Enviar mensajes a AiHummer: [Disparadores de entrada e integración](/es/v1.0/api/inbound-triggers). - Alterna estas superficies y más: [Variables de entorno](/es/v1.0/reference/env-vars). - Operar la instancia: [Referencia de CLI](/es/v1.0/reference/cli).