5.1 KiB
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 (eigeneprisma/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
WebhookSubscriptionsHMAC-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) — HauptquelleROADMAP.md→ Phase 22PHASE-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-P22baktualisiert