Webhooks, SCIM et jumelage

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

Cette page couvre les surfaces de protocole restantes : **appairage de l'appareil**, entreprise **fédération d'authentification** (SAML / SCIM / OAuth), l'adhésion volontaire **Serveur MCP** et **A2A** points de terminaison, **média** transfert, et le **Connect-RPC** services. Plusieurs d'entre eux sont désactivés par défaut et doivent être activés explicitement. ## Appairage de l'appareil Les clients mobiles et de bureau rejoignent une instance via un court échange d'appairage (l'application iOS/macOS utilise uniquement l'appairage par QR). | Méthode et chemin | But | |---|---| | `POST /v1/pairing/redeem` | Échanger un code de jumelage et configurer l'appareil | | `POST /v1/pairing/device/validate` | Valider un appareil déjà appairé | ```bash curl https://your-aihummer.example/v1/pairing/redeem \ -H "Content-Type: application/json" \ -d '{ "code": "ABCD-EFGH" }' ``` ## Fédération d'authentification AiHummer s'intègre aux fournisseurs d'identité d'entreprise pour la connexion et la fourniture des utilisateurs. ### SAML | Méthode et chemin | But | |---|---| | `GET /saml/metadata` | Métadonnées du fournisseur de services pour votre IdP | | `POST /saml/acs` | Service consommateur d'assertion (réponse SAML) | | `GET /saml/login` | Initier la connexion SAML | ### Approvisionnement SCIM Le Système de Gestion d'Identité Inter-domaines (SCIM 2.0) permet à votre IdP de créer et gérer des utilisateurs automatiquement. | Méthode et chemin | But | |---|---| | `.../scim/v2/Users` | Lister / créer des utilisateurs | | `.../scim/v2/Users/{id}` | Lire / mettre à jour / supprimer un utilisateur | Les points de terminaison SCIM s'authentifient avec un **jeton porteur SCIM par locataire**, délivré (et renouvelé/révoqué) à `POST /v1/admin/scim/token`; l'IdP l'envoie dans un `Authorization: Bearer` en-tête. Le jeton est affiché une fois au moment de l'émission. ### Jeton OAuth | Méthode et chemin | But | |---|---| | `POST /v1/oauth/token` | Point de terminaison du jeton OAuth | ## Serveur MCP (publier vers l'extérieur) AiHummer peut publier ses propres outils aux clients MCP en agissant comme un **Serveur MCP**. Ceci est **s'inscrire** et désactivé à moins que vous ne configuriez `AIHUMMER_MCP_PUBLISH=1`. | Méthode et chemin | But | |---|---| | `POST /v1/mcp` | Point de terminaison du serveur MCP (nécessite `AIHUMMER_MCP_PUBLISH=1`) | > [!WARNING] > **`AIHUMMER_MCP_PUBLISH=1` seul ne suffit pas.** Il ouvre l'adresse, mais la > liste d'export reste vide : `tools/list` renvoie un tableau vide et tout appel > est refusé. Énumérez les outils voulus par **nom exact, séparés par des > virgules**, dans `AIHUMMER_MCP_EXPORT_TOOLS` — les motifs et `*` ne sont pas > pris en charge. Seuls les outils de **lecture** peuvent être publiés : > `http_request`, `web_fetch`, `browser`, `code_exec` et `filesystem_read` ne > sont jamais exportés, même si vous les nommez. > > Les deux réglages se définissent dans **Gestion → Réglages** ou avec > `aihummer settings set`, pas dans `gateway.env` — l'environnement est ignoré > pour ces clés. `AIHUMMER_MCP_PUBLISH` accepte exactement `1` : `true` ou > `on` laissent l'adresse fermée. Les changements prennent effet après un > redémarrage de la passerelle. > > Le client doit envoyer une clé API portant la portée `mcp` dans l'en-tête > `Authorization: Bearer …` ; sans elle, la réponse est 401. > [!NOTE] > La publication d'outils vers l'extérieur est distincte de *consommer* un serveur MCP en tant que > Intégration sans code. Ce point de terminaison permet aux autres clients MCP d’appeler > AiHummer. ## A2A (Agent à Agent) AiHummer peut exposer une surface A2A afin que d'autres agents puissent la découvrir et lui envoyer des messages. Ceci est également **s'inscrire** via `AIHUMMER_A2A_PUBLISH=1`. | Méthode et chemin | But | |---|---| | `GET /.well-known/agent.json` | Carte d'agent A2A / document de découverte | | `POST /a2a/message` | Recevoir un message A2A (requiert `AIHUMMER_A2A_PUBLISH=1`) | ## Média Les médias volumineux (audio, images, fichiers) sont téléchargés et récupérés via des points de terminaison dédiés plutôt que d'être intégrés dans les corps JSON. | Méthode et chemin | But | |---|---| | `PUT /v1/media/{id}/content` | Téléchargez les octets pour un objet média | | `GET /v1/files/{id}` | Télécharger un fichier stocké | > [!TIP] > Ensemble `AIHUMMER_BLOB_DIR` pour activer le service de médias/fichiers, et > `AIHUMMER_MEDIA_TOKEN_SECRET` afin que les URL de téléchargement signées restent valides sur > redémarre. ## Services Connect-RPC Pour les clients tapés et en streaming, AiHummer expose également **Connect-RPC** services sur HTTP (le streaming côté serveur est pris en charge) : | Service | Zone | |---|---| | `aihummer.health.v1` | Contrôles de santé | | `aihummer.event.v1` | Flux d'événements | | `aihummer.conversation.v1` | Conversations | | `aihummer.push.v1` | Livraison push | | `aihummer.media.v1` | Transfert de médias | | `aihummer.turn.v1` | Exécution de tour | ## Où aller ensuite - Pousser des messages dans AiHummer : [Déclencheurs entrants et d'intégration](/fr/v1.0/api/inbound-triggers). - Basculez ces surfaces et plus encore : [Variables d'environnement](/fr/v1.0/reference/env-vars). - Exécuter l'instance : [Référence CLI](/fr/v1.0/reference/cli).