Webhooks, SCIM și Asociere

v1.2.x · actualizat 2026-07-05

Această pagină acoperă suprafețele de protocol rămase: împerecherea dispozitivelor, întreprindere federație de autentificare (SAML / SCIM / OAuth), opțiunea de înscriere server MCP și A2A puncte finale, media transfer, și Conectare-RPC servicii. Mai multe dintre acestea sunt dezactivate implicit și trebuie activate în mod explicit.

Împerecherea dispozitivului

Clienții mobili și desktop se conectează la o instanță printr-un scurt schimb de asociere (aplicația iOS/macOS folosește doar asociere prin QR).

Metodă și cale	Scop
`POST /v1/pairing/redeem`	Răscumpărați un cod de asociere și provisionați dispozitivul
`POST /v1/pairing/device/validate`	Validează un dispozitiv deja împerecheat

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

Federație de autentificare

AiHummer se integrează cu furnizorii de identitate enterprise atât pentru autentificare, cât și pentru provisioning-ul utilizatorilor.

SAML

Metodă și cale	Scop
`GET /saml/metadata`	Metadate ale furnizorului de servicii pentru IdP-ul tău
`POST /saml/acs`	Serviciu de Consum al Afirmărilor (răspuns SAML)
`GET /saml/login`	Inițiați autentificarea SAML

Provisionarea SCIM

Sistemul pentru Gestionarea Identității între Domenii (SCIM 2.0) permite IdP-ului dvs. să creeze și să gestioneze utilizatori automat.

Metodă și cale	Scop
`.../scim/v2/Users`	Listează / creează utilizatori
`.../scim/v2/Users/{id}`	Citește / actualizează / șterge un utilizator

Punctele finale SCIM se autentifică cu un token purtător SCIM per-chiriaș, emis (și rotit/revocat) la POST /v1/admin/scim/token; IdP-ul îl trimite într-un Authorization: Bearer antet. Tokenul este afișat o singură dată la momentul emiterii.

token OAuth

Metodă și cale	Scop
`POST /v1/oauth/token`	Punct final pentru token OAuth

Server MCP (publicare către exterior)

AiHummer poate publica propriile sale instrumente către clienții MCP acționând ca un server MCP. Acesta este a opta și dezactivat decât dacă setezi AIHUMMER_MCP_PUBLISH=1.

Metodă și cale	Scop
`POST /v1/mcp`	Punct final al serverului MCP (necesită `AIHUMMER_MCP_PUBLISH=1`)

[!WARNING] Doar AIHUMMER_MCP_PUBLISH=1 nu este de ajuns. Deschide adresa, dar lista de export este goală: tools/list întoarce un tablou gol, iar orice apel este refuzat. Enumerați uneltele dorite cu nume exacte, separate prin virgulă, în AIHUMMER_MCP_EXPORT_TOOLS — tiparele și * nu sunt acceptate. În exterior pot merge doar unelte de citire: http_request, web_fetch, browser, code_exec și filesystem_read nu sunt exportate niciodată, chiar dacă le numiți.

Ambele setări se dau din Administrare → Setări sau cu aihummer settings set, nu în gateway.env — pentru aceste chei mediul este ignorat. AIHUMMER_MCP_PUBLISH acceptă exact 1: true sau on lasă adresa închisă. Modificările au efect după repornirea gateway-ului.

Clientul trebuie să trimită o cheie API cu domeniul mcp în antetul Authorization: Bearer …; fără ea răspunsul este 401.

[!NOTE] Publicarea uneltelor în exterior diferă de consumarea unui server MCP ca integrare fără cod. Acest punct final este pentru a permite altor clienți MCP să apeleze în AiHummer.

A2A (Agent-la-Agent)

AiHummer poate expune o suprafață A2A astfel încât alți agenți să o poată descoperi și să îi trimită mesaje. Acesta este de asemenea a opta prin AIHUMMER_A2A_PUBLISH=1.

Metodă și cale	Scop
`GET /.well-known/agent.json`	Card agent A2A / document de descoperire
`POST /a2a/message`	Primește un mesaj A2A (necesită `AIHUMMER_A2A_PUBLISH=1`)

Media

Media de mari dimensiuni (audio, imagini, fișiere) este încărcată și preluată prin puncte finale dedicate în loc să fie încorporată în corpuri JSON.

Metodă și cale	Scop
`PUT /v1/media/{id}/content`	Încarcă octeții pentru un obiect media
`GET /v1/files/{id}`	Descarcă un fișier stocat

[!TIP] Set AIHUMMER_BLOB_DIR pentru a activa serviciul media/fișiere și AIHUMMER_MEDIA_TOKEN_SECRET astfel încât URL-urile de descărcare semnate să rămână valabile în întreaga repornește.

Servicii Connect-RPC

Pentru clienții tastati și de streaming, AiHummer de asemenea expune Conectare-RPC servicii prin HTTP (se suportă streaming de la server):

Serviciu	Zonă
`aihummer.health.v1`	Verificări de sănătate
`aihummer.event.v1`	Flux de evenimente
`aihummer.conversation.v1`	Conversații
`aihummer.push.v1`	Livrare push
`aihummer.media.v1`	Transfer de media
`aihummer.turn.v1`	Execuția pe ture

Unde următor?

Trimite mesaje către AiHummer: Declanșatoare de intrare și integrare.
Comută aceste suprafețe și altele: Variabile de mediu.
Operare instanța: Referință CLI.