Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/VR-P22b.md
T

5.1 KiB

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