58 lines
5.0 KiB
Markdown
58 lines
5.0 KiB
Markdown
# 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:
|