# 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](https://developer.aircall.io/tutorials/how-aircall-oauth-flow-works/), [Aircall API Reference](https://developer.aircall.io/api-references/) und [Aircall Sandbox](https://support.aircall.io/en-gb/articles/23108614387485-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.