5.2 KiB
VD-P22 · Screens P22 — Public-API-Keys-UI & Webhooks
| Typ | Screen (Design) |
| Owner | David |
| Phase | P22 — Public-API & Webhooks (v2-P1) · bedient VR-P22a/VR-P22b |
| Cycle/Fenster | v2-W1 — Public-API/Postfach/Abo/KI-Start · 2026-07-13 → fällig 2026-07-17 |
| Status | geplant (NEU — Phasen-Ticket) |
♻️ Löst Sammel-Ticket auf: Dieses Phasen-Ticket ersetzt — zusammen mit
VD-P28undVD-P32— das alte Sammel-TicketVD-5(„Public-API-Keys + Admin-Tiefe + KWP-Setup"). VD-P22 = der Public-API-Keys-/Webhooks-Anteil.
Abhängigkeiten & Parallelität
- Blocked by: D0-Baseline (
D-D0aApp-Shell,D-D0bArchetypen A2–A6) — die API-Key-Verwaltung ist eine Erweiterung der vorhandenen v1-ApiKey-Fläche (M027), kein Neubau; komponiert aus den D0-Archetypen - Bedient (Dev):
VR-P22a(OpenAPI + Read-Endpoints, M161),VR-P22b(API-Key-Auth/Scopes/Rate-Limit) — beide v2-W1 (13.–17.07.) - Läuft parallel zu:
VD-P23(Postfach),VD-P24(Abo/Wizard) — gleiche v2-W1 - Subframe: Pflicht je Route (A2 Liste, A3 Detail, A5 Modal, A6 Settings; Swagger-UI = extern/eingebettet)
Was wir bauen
Die Verwaltungs-Oberfläche der Public-API: Tenant-API-Keys (Scopes, Rate-Limit, Tarif-Gate), eingehende Lead-Webhooks (Payload-Mapping + Auto-Match), ausgehende signierte WebhookSubscriptions (Delivery-Log, Replay), API-Request-/Usage-Logs sowie die auto-generierte OpenAPI/Swagger-Doku. Secrets folgen dem Copy-once-Muster (einmalig sichtbar). Read-only-REST + Webhooks — bewusst kein Voll-CRUD/GraphQL/OAuth.
Host-Contract: Public API läuft nur auf api.hivegrid.de (staging: staging-api.hivegrid.de) mit /v1/....
Keine Public-API-Routen unter app.hivegrid.de/api.
Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
API-Key-Verwaltung [/admin/api-keys] |
Key-Liste (Name, Scopes, letzte Nutzung, Status, Tarif-Gate); Key erstellen (Scope-Auswahl, Secret einmal sichtbar); Rotieren/Widerrufen | A2 + A5 (Erweiterung v1) |
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 (Eingang/Match/Fehler) |
A2 + A3 |
Outgoing-Subscription-Liste [/admin/webhooks] |
Ziel-URL, abonnierte Event-Typen, Status (aktiv/auto-disabled), letzte Zustellung, Fehlerzähler | A2 |
Outgoing-Subscription-Detail [/admin/webhooks/:id] |
Secret (einmal sichtbar), Delivery-Stats, Delivery-Log mit Retry-Status, Replay/Test-senden, Aktivieren/Pausieren | A3 |
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-Auslastung) | A2 |
OpenAPI/Swagger-UI [api.hivegrid.de/v1/openapi.json · Swagger auf API-Host] |
Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet, evtl. eingebettete Drittanbieter-UI) | A6/extern |
(Die REST-Endpoints api.hivegrid.de/v1/contacts|companies|deals|projects|tasks|leads sind serverseitig — kein eigener Screen außer Swagger-UI.)
Features (muss abgedeckt sein)
- API-Key-Verwaltung als Erweiterung der v1-
ApiKey-Fläche (Scope-Auswahl, Secret Copy-once, Rotieren/Widerrufen) - Read-Endpoint-Doku (contacts/companies/deals/projects/tasks/leads, cursor-paginiert, Filter/Sort/Sparse/Embed)
read_only-Scope blendet sensible Felder aus (Feld weglassen, nicht 403) — in der UI transparent- Rate-Limit-/Quota-Anzeige (1k/h pro Key, 10k/h pro Tenant) + Klartext-429-Hinweis
- Incoming-Lead-Webhooks (Auth-Modus + Payload-Mapping + Auto-Match) inkl. Ingestion-Log
- Outgoing-WebhookSubscriptions: HMAC-SHA256-Signatur, Idempotenz, Retry/Backoff, Auto-Disable nach 10 Fehlern, Replay/Test
- OpenAPI-3.1 + Swagger-UI eingebunden
- Tarif-Gate (M027): API-Keys/Webhooks nur im passenden Abo → Upgrade-Prompt
UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Daten-Tabelle (sortierbar, paginiert) für Keys/Webhooks/Logs; „Secret/Token einmal sichtbar"-Reveal mit Copy-Button + Warnhinweis; Scope-Multi-Select (Checkbox-Gruppe); Status-Badges (aktiv/pausiert/auto-disabled); Tarif-Gate-Hinweis/Upgrade-Prompt; Payload-Mapping-Editor (Feld-zu-Feld-Zuordnung); Auth-Modus-Auswahl (API-Key/HMAC/URL-Token); Delivery-Log-Timeline mit Retry-Status-Marker; Replay-/Test-senden-Button; Rate-Limit-/Quota-Auslastungs-Anzeige (Balken/Zahl); Code-Snippet-Block (HMAC-Verifizierungs-Beispiel); 429-/Fehler-Hinweis-Banner; Empty-/Loading-/Permission-Denied-States (Klartext).
Quellen (granular)
designer-briefs/P22-public-api-webhooks.md(vollständiger Brief — diese Doc ist sein Ticket-Destillat)ENTITY-MODEL.md→ Domäne 4 (Apps-Engine) +ApiKey(v2, „wandert mit Public-API"),WebhookSubscriptionROADMAP-V2.md§v2-P1 (Screens/Features = Hauptquelle) ·ROADMAP.md§Phase 22 ·_bmad-output/specs/M34-public-api.md- Plane-Snapshot: ersetzt Teil von
VD-5; bedientVR-P22a/VR-P22b(v2-W1, 13.–17.07.)
Davids Delta (David füllt aus)
- Überschriebene/geänderte Spec-Punkte:
- Neue UI/UX-Entscheidungen:
- Subframe-Screen-Link(s):
- Offene Fragen an Dev: