Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/EXT-08.md
T

6.9 KiB

EXT-08 · AirCall Technology-Partner-OAuth + Live-Zugang (keine Sandbox)

Typ Setup (External)
Owner Raffael
Cycle/Fenster Just-in-time vor der Live-Verifikation von AK-P15a
Status geplant · blockiert nur den Live-Proof, nicht den Fixture-first-Bau

Vertragskorrektur 2026-07-15: HiveGrid ist eine Integration für mehrere Aircall-Companies und verwendet deshalb den offiziellen Technology-Partner-OAuth-Flow. api_id/api_token per Basic Auth ist laut Aircall nur für eine Integration in das eigene Aircall-Konto gedacht und ist nicht der HiveGrid-Vertrag.

Verifizierter Aircall-Vertrag

  • Aircall bietet keine dedizierte Sandbox. Live-Verifikation erfolgt in einem echten Partner-/Trial-Account mit Test-Usern und ausgewählten Test-Nummern; Seats/Nummern können kostenpflichtig sein.
  • Aircall stellt für die Technology-Partner-App client_id und client_secret bereit. Diese sind umgebungsweite App-Secrets, keine Tenant-Credentials, und liegen ausschließlich in den jeweiligen Coolify-Secrets für Staging/Produktion.
  • Der Authorization-Code ist zehn Minuten gültig und wird über POST https://api.aircall.io/v1/oauth/token gegen einen permanenten Bearer-access_token getauscht. Der Token läuft laut Aircall-Vertrag nicht ab; es gibt für diesen Flow keinen Refresh-Token und keinen Refresh-Worker.
  • Installationen sind auf Aircall-Company-Ebene. Die Person, die in HiveGrid als Tenant-Admin verbindet, muss deshalb zugleich Admin der betreffenden Aircall-Company sein. Andernfalls kann sie die App nicht autorisieren.
  • Nach dem Token-Tausch legt HiveGrid den Webhook über POST https://api.aircall.io/v1/webhooks an. Aircall liefert dabei einen eindeutigen Webhook-token, der in jedem Event mitgesendet und zur Connection-Zuordnung geprüft wird. Aircall liefert für diesen Vertrag keine HMAC-Signatur; HMAC darf daher nicht vorgetäuscht werden. Pflicht bleiben TLS, Payload-/Event-Allowlist, Token-Abgleich, Idempotenz und Rate-Limit.
  • Bei OAuth wählt der Aircall-Company-Admin die Aircall-Nummern aus, deren Call-Events an die Integration gehen.

Offizielle Quellen: Aircall OAuth für Technology Partners, Aircall API Reference und Aircall Sandbox.

Registrierte URLs

Zweck Produktion Staging
Aircall install_uri https://app.hivegrid.de/integrations/aircall/oauth/install https://staging-app.hivegrid.de/integrations/aircall/oauth/install
Aircall redirect_uri / Callback https://app.hivegrid.de/integrations/aircall/oauth/callback https://staging-app.hivegrid.de/integrations/aircall/oauth/callback
automatisch angelegter Webhook https://api.hivegrid.de/v1/webhooks/telephony/aircall https://staging-api.hivegrid.de/v1/webhooks/telephony/aircall

Der install_uri erzeugt einen kurzlebigen, signierten OAuth-state (Tenant, initiierender User, Nonce) und leitet mit client_id, festem redirect_uri, response_type=code, scope=public_api und state an https://dashboard.aircall.io/oauth/authorize weiter. Der Callback prüft den state; Tenant-Identität steht weder im Callback- noch im Webhook-Pfad.

Getrennter Admin-Sales-Vertrag für VA-P28d

Zweck Produktion Staging
Aircall Admin-Connect https://admin.hivegrid.de/sales/settings/telephony/connect/aircall https://staging-admin.hivegrid.de/sales/settings/telephony/connect/aircall
Aircall Admin-Callback https://admin.hivegrid.de/sales/settings/telephony/callback/aircall https://staging-admin.hivegrid.de/sales/settings/telephony/callback/aircall
Admin-Sales-Webhook https://api.hivegrid.de/v1/webhooks/admin-telephony/aircall https://staging-api.hivegrid.de/v1/webhooks/admin-telephony/aircall

Der Admin-Sales-Flow bindet OAuth-State, Connection und Call-Daten ausschließlich an einen aktiven AdminUser und AdminDataConnection. Er verwendet weder Tenant-IDs noch Tenant-RLS oder die produktiven Tenant-Redirects. Das Aircall-Partner-App-Setup muss beide klar getrennten URL-Sätze registrieren; der Live-Proof für VA-P28d bleibt bis dahin extern blockiert.

Was extern zu tun ist

  • Technology-Partner-App bei Aircall mit den Install-/Callback-URLs registrieren und client_id/ client_secret getrennt für die vorgesehenen Umgebungen sicher bereitstellen.
  • Aircall-Konto (Trial oder bezahlt) mit Aircall-Company-Admin, Test-Usern und gegebenenfalls kostenpflichtigen Test-Nummern bereitstellen.
  • Die HiveGrid-App durch den Company-Admin installieren, Nummern auswählen und den permanenten Access Token via Callback erzeugen; danach /v1/ping, User-Liste und Click-to-Call live prüfen.
  • Den Webhook automatisiert anlegen und mindestens die vereinbarten Call-Events live gegen Staging verifizieren.

Fixture-first vs. Live-Verifikation

AK-P15a beginnt fixture-first: OAuth-State/Callback, Token-Tausch, API-Mapping, Webhook-Normalisierung, Idempotenz und Fehlerpfade werden gegen versionierte Fixtures und HTTP-Fakes gebaut. EXT-08 blockiert nur den abschließenden Live-Proof mit echtem Aircall-Account, echter Nummernauswahl, Callback, Call und Webhook. Ohne diesen Proof bleibt AK-P15a unter 100 %, der restliche Bau ist aber nicht blockiert.

Warum / was es blockt

  • Blocks: ausschließlich die Live-Verifikationspunkte von AK-P15a und VA-P28d, nicht deren Fixture-first-Umsetzung.

Abhängigkeiten

  • blocked-by: Aircall Technology-Partner-Onboarding und Verfügbarkeit eines Aircall-Company-Admins mit Test-User/-Nummer (extern)
  • blocks: AK-P15a Live-Proof
  • Auswirkung auf Abhängige (2026-07-15): AK-P15a wird fixture-first entblockt; D-P15 ist nach AD-28 kein Dev-Blocker. AK-P15b (Chat) erhält durch den Aircall-Auth-Vertrag keine technische Änderung.
  • Auswirkung auf Abhängige (2026-07-24): VA-P28d verwendet einen separaten, tenantlosen Admin-Sales-OAuth-/Webhook-Vertrag. Der Codebau bleibt fixture-first entblockt; nur der kontrollierte Admin-Live-Proof wartet auf die zusätzliche Partner-App-Registrierung.

Definition of Done

  • Technology-Partner-App/OAuth-Credentials für die benötigten Umgebungen vorhanden; Install-/Callback-URLs sind bei Aircall registriert
  • Aircall-Company-Admin + Test-User/-Nummer vorhanden und Nummernauswahl im Install-Flow durchgeführt
  • Permanenter Access Token per Callback erzeugt, verschlüsselt gespeichert und mit /v1/ping live geprüft
  • Webhook per OAuth-Bearer angelegt; Webhook-Token-Zuordnung, Rate-Limit und mindestens ein echtes Call-Event auf Staging nachgewiesen

Umsetzungs-Notiz

  • 2026-07-15 · 0/4 DoD = 0 % done: Planungsvertrag auf Technology-Partner-OAuth korrigiert. Keine DoD als umgesetzt markiert; Live-Zugang und Live-Proof bleiben extern offen.