# VR-P22b · Public-API: API-Key-Auth/Scopes/Rate-Limit (M162/M027) + Webhooks (M163) | | | |---|---| | **Typ** | Dev (Code) | | **Owner** | Raffael | | **Phase** | Phase 22 (v2-P1) — Public-API & Webhooks | | **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-17 | | **Status** | geplant | ## Abhängigkeiten & Parallelität - **Blocked by:** `VR-P22a` (Read-Endpoints + OpenAPI), `R-P12a` (v1-Automation: `external_event`-Trigger + ausgehende Webhook-Action) - **Blocks:** — (Phase 22 endet hier) - **Läuft parallel zu:** `VA-P23` (Postfach-Sync, Akeshan) — **geteilte Webhook-Ingest-Infra**: einmal robust bauen, beide nutzen sie. Abstimmung mit Akeshan zum gemeinsamen Ingest-Endpoint/HMAC-Verify-Layer; kein Schema-Konflikt (eigene `prisma/schema/publicApi.prisma`, AD-21). - **Konflikt-Risiko:** gering — nur die geteilte Webhook-Ingest-Infra braucht Koordination (Owner = Raffael, Akeshan dockt an). ## Was wir bauen Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API. API-Keys authentifizieren Requests mit **Scopes** und **Rate-Limit** (1k/h pro Key, 10k/h pro Tenant, `X-RateLimit-*`-Header + Klartext-429). **Eingehende Lead-Webhooks** (`POST /webhooks/incoming/{tenant}/{slug}`) legen Leads an (API-Key/HMAC/URL-Token + Payload-Mapping + Auto-Match). **Ausgehende `WebhookSubscriptions`** senden Events HMAC-SHA256-signiert mit Idempotenz-ID, Retry mit exp. Backoff (max 5) und Auto-Disable nach 10 Fehlern; die ausgehende Webhook-**Action** dockt an die v1-Automation (`external_event`-Trigger) an. Tarif-Gates (M027) machen API-Keys/Webhooks abo-abhängig. ## Benötigte Screens (Backend bedient — Design liefert `D-P22`) | Screen [Route] | Kern-Inhalt | |---|---| | API-Key-Verwaltung [`/admin/api-keys`] | Key-Liste (Name/Scopes/letzte Nutzung/Status/Tarif-Gate) · Key erstellen (Scope-Auswahl, **Secret einmal sichtbar**) · Rotieren/Widerrufen — Erweiterung der v1-Fläche | | Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln · Ingestion-Log | | Outgoing-Subscription-Liste [`/admin/webhooks`] | Ziel-URL, Event-Typen, Status (aktiv/auto-disabled), letzte Zustellung, Fehlerzähler | | Outgoing-Subscription-Detail [`/admin/webhooks/:id`] | **Secret einmal sichtbar**, Delivery-Stats, Delivery-Log mit Retry-Status, Replay/Test-senden, Aktivieren/Pausieren | | API-Request-Logs + Usage [`/admin/api-keys/usage`] | Request-Log (Endpoint/Key/Status/Latenz/Rate-Limit-Treffer) · Usage-Aggregat (Calls/h pro Key + Tenant, Quota) | ## Definition of Done - [ ] **API-Key-Auth** + **Scopes** + **Rate-Limit** (1k/h Key, 10k/h Tenant) + `X-RateLimit-*`-Header + Klartext-429 - [ ] **Eingehende Lead-Webhooks** (API-Key/HMAC/URL-Token) + Payload-Mapping + **Auto-Match** (From/Pattern → Contact/Lead) - [ ] **Ausgehende `WebhookSubscriptions`** HMAC-SHA256-signiert, Idempotenz-ID, Retry exp. Backoff (max 5), **Auto-Disable nach 10 Fehlern** - [ ] **Tarif-Gates (M027):** API-Keys/Webhooks nur im passenden Abo verfügbar (`tenantHasModule('public_api')`) - [ ] **Writes** durch v1-Frozen/past_due-Middleware geblockt (**402**) - [ ] Secret/Webhook-Signing-Secret **einmalig sichtbar** (Copy-once-Muster), nur Hash persistiert - [ ] Ausgehende Webhook-Action an v1-Automation (`external_event`-Trigger) angedockt ## Technische Bausteine - **Entities** (eigene `prisma/schema/publicApi.prisma`, AD-21): `ApiKey` (`key_hash`, `scope`, `expires_at`, [RLS][Soft-Delete] — Auth-Pfad hier vollständig), `WebhookSubscription` (Ziel-URL, abonnierte Event-Typen, Signing-Secret-Hash, Status, Fehlerzähler), Incoming-Webhook-Endpoint (Slug, Auth-Modus, Payload-Mapping), Delivery-/Ingestion-Log (append-only). Lead-Anlage über die CRM-Domäne (Lead-Entity), nur referenziert. - **RLS:** alles Tenant-bezogene mit `app.tenant_id`; eingehende Webhooks setzen den Tenant aus dem Slug/`{tenant}`-Pfadsegment. - **Rate-Limit:** Redis-Token-Bucket (geteilt mit v1-Redis), Key- und Tenant-Bucket getrennt. - **HMAC:** SHA256 für ein- und ausgehend; Signatur-Header + dokumentiertes Format (Code-Snippet für Verifizierung im UI). - **Webhook-Ingest-Infra:** geteilter Layer mit VA-P23 (Postfach-Sync) — einmal robust, idempotent. - **Konnektor:** `tenantHasModule('public_api')` + Tarif-Gate (M027, `SubscriptionFeature.code`). - **`is_demo_data`:** ggf. Demo-Webhook-Subscriptions geseedet (Bulk-Löschung beim Echt-Start). ## Quellen (granular) - `ROADMAP-V2.md` → §v2-P1 (Success-Criteria 2/3, alle Screens) — **Hauptquelle** - `ROADMAP.md` → Phase 22 - `PHASE-SOURCES.md` → Phase 22 (M162/M163 + M027 API-Keys & Tarif-Gates; M027-Scope-Schnitt 12.06.) - `ENTITY-MODEL.md` → `ApiKey` [v2], `WebhookSubscription`, `SubscriptionFeature.code` (Tarif-Gate-Brücke) - `designer-briefs/P22-public-api-webhooks.md` (alle Verwaltungs-Screens, Copy-once-Muster) - `_bmad-output/specs/M34-public-api.md` (Auth/Webhooks-Teil) ## Dev-Nachzug (nach Davids `D-P22`-Delta) - [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst - [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen - [ ] Plane-Ticket `VR-P22b` aktualisiert