# 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-P28` und `VD-P32` — das alte Sammel-Ticket **`VD-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-D0a` App-Shell, `D-D0b` Archetypen 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. ## 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, 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/v1/openapi` · Swagger] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet, evtl. eingebettete Drittanbieter-UI) | A6/extern | *(Die REST-Endpoints `/api/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"), `WebhookSubscription` - `ROADMAP-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`; bedient `VR-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: