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_tokenper 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_idundclient_secretbereit. 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/tokengegen einen permanenten Bearer-access_tokengetauscht. 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/webhooksan. 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_secretgetrennt 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-P15aundVA-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-P15aLive-Proof - Auswirkung auf Abhängige (2026-07-15):
AK-P15awird fixture-first entblockt;D-P15ist 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-P28dverwendet 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/pinglive 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.