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

7.7 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 On Hold — serverseitig umgesetzt, Admin-Screens/UX aus D-P22 fehlen

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 auf api.hivegrid.de (staging: staging-api.hivegrid.de). Es gibt keine Public-API- oder Public-Webhook-Routen unter app.hivegrid.de/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 https://api.hivegrid.de/v1/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 auf api.hivegrid.de/v1/webhooks/..., 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 auf api.hivegrid.de/v1/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.
  • Host-Surface: Public API und Public-Webhooks laufen nur im hivegrid-api-Service (api.hivegrid.de / staging-api.hivegrid.de), nie im Web-Service (app.hivegrid.de/api ist verboten).
  • 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
  • Historische Milestone-Zuordnung: 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)

Dev-Nachzug (nach Davids D-P22-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket VR-P22b aktualisiert

Umsetzungsnotiz

2026-07-03 — Server-DoD umgesetzt, Ticket auf On Hold bis D-P22:

  • API-Key-Scopes, Legacy-Read-Kompatibilität, Key-/Tenant-Rate-Limits und X-RateLimit-*-Header für GET /v1/... ergänzt.
  • POST /v1/webhooks/incoming/{tenant}/{slug} auf dem API-Service (api.hivegrid.de) ergänzt: URL-Token, HMAC und API-Key-Auth, Payload-Mapping, Lead-Anlage, Kontakt-Auto-Match, Ingestion-Log, Tarif-Gate und 402 bei frozen/past_due.
  • prisma/schema/publicApi.prisma, Migration 20260703090000_vr_p22b_public_api_webhooks und RLS-Rollout-Datei für Incoming-Endpoints, Ingestion-Logs, Outgoing-Subscriptions und Delivery-Logs ergänzt.
  • Outgoing-Subscription-Service ergänzt: Copy-once Signing-Secret, Hash-only-Persistenz, HMAC-Signatur, Idempotenz-Key, Delivery-Log, exponential Backoff bis 5 Versuche und Auto-Pause nach 10 Fehlern.
  • v1-Automation ist angebunden: eingehende Webhooks erzeugen AutomationExecution für webhook.received mit triggerPayload.source = "external_event"; die bestehende http.request-Action bleibt der ausgehende Webhook-Action-Pfad.
  • OpenAPI, Route-Access-Inventar, Security-Doku, Tenant-Registry und Tests nachgezogen.

Proof: pnpm exec prisma validate; pnpm --filter @hivegrid/api typecheck; pnpm --filter @hivegrid/db typecheck; pnpm --filter @hivegrid/cli typecheck; fokussierte Vitest-Suite für Public-API/OpenAPI/Route-Inventar/DB; pnpm run verify:api-inventory; pnpm run verify:openapi-security; node scripts/verify-cross-cutting-models-complete.mjs; pnpm typecheck; pnpm lint; pnpm test.

Stand: 7/7 Server-DoD = 100 % serverseitig. Gesamtticket bleibt On Hold, weil die Verwaltungs-Screens aus D-P22 noch fehlen: API-Key-Verwaltung, Incoming-Webhooks, Outgoing-Subscriptions, Detail/Replay und Usage-Logs.

2026-07-12 — Abhängigkeits-Nachzug aus VR-MCP: Die MCP-spezifische OAuth-Scope-Fläche wurde additiv um mcp:activity:read, mcp:task:read und mcp:task:write erweitert. Die bestehenden Bündel mcp:read und mcp:write decken diese granularen Scopes weiterhin ab. Public-REST-API, API-Key-/Webhook-Schema, Rate-Limits und der 7/7-Server-DoD dieses Tickets bleiben unverändert; es entsteht kein neuer Blocker für VR-P22b.