Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M34-public-api.md
T

23 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
34 Public API & Webhooks 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-6
LP-9
LP-10
LP-11
LP-13
requirements-pur

Modul 34 — Public API & Webhooks

Detail-Spec gemäß LP-9. Phase-1-Basic. Read-API (GET) für Hauptentitäten + eingehende Webhooks für Lead-Push + ausgehende Webhooks als Automation-Engine-Action (M17). API-Key-Verwaltung kommt aus M27 Block E. OpenAPI-Doku auto-generiert. Voll-CRUD-API erst Phase 2 (bewusste Scope-Beschränkung).

Themenblöcke

A. Datenmodell (Logging und Webhook-Subscriptions)
B. Authentifizierung & Scopes (Verweis auf M27 Block E)
C. Read-API (GET-Endpoints für Hauptentitäten)
D. Eingehende Webhooks (Lead-Push)
E. Ausgehende Webhooks (Subscription-Modell)
F. Allgemeine Event-Ingestion
G. OpenAPI-Doku
H. Rate-Limiting
I. Versionierung & Stabilität
J. Permissions / Scope-Mapping
K. Phase 2

Block A — Datenmodell

IntegrationApiRequest

Audit-Log aller eingehenden API-Requests. Tenant-scoped.

  • id, tenant_id, created_at
  • api_key_id (FK auf ApiKey aus M27 — nullable bei unauth Requests)
  • route_pattern (z.B. /api/v1/contacts/:id)
  • http_method (GET / POST / PUT / DELETE)
  • query_params (JSONB — sanitized)
  • request_body_size_bytes
  • response_status_code (Integer)
  • response_size_bytes
  • duration_ms
  • client_ip
  • user_agent
  • error_message (nullable, Klartext)

Indizes:

  • (tenant_id, api_key_id, created_at DESC) — pro-Key-Logs
  • (tenant_id, route_pattern, created_at DESC) — pro-Endpoint-Stats
  • (tenant_id, response_status_code, created_at DESC) — Error-Monitoring

Retention: 90 Tage, danach gelöscht (außer 4xx/5xx → 180 Tage).

WebhookSubscription

Definition eines vom Tenant abonnierten ausgehenden Webhooks. Tenant-scoped.

  • id, tenant_id, created_at, updated_at, created_by_user_id
  • name (interner Name)
  • target_url (URL, an die ausgehende Events gesendet werden)
  • secret_encrypted (für HMAC-Signatur)
  • event_types[] (Liste der abonnierten Events, z.B. contact.created, deal.stage_changed, project.completed)
  • filter_definition (optional — JSONB für event-spezifische Filter)
  • is_active (Boolean)
  • failure_count_consecutive (Integer — Auto-Disable nach N Fehlern)
  • last_success_at, last_failure_at, last_failure_reason
  • archived_at

Indizes: (tenant_id, is_active, event_types) für Event-Dispatch.

WebhookDelivery

Pro Event-Auslösung pro Subscription ein Eintrag.

  • id, tenant_id, subscription_id, created_at
  • event_type, event_id (für Idempotenz beim Empfänger)
  • payload (JSONB — finaler Body)
  • status (Enum: pending | delivered | failed | exhausted | discarded)
  • attempt_count (Integer, max. 5)
  • last_attempt_at, delivered_at
  • last_response_status_code, last_response_body_excerpt (max. 500 Zeichen)

Indizes: (tenant_id, subscription_id, status), (status, last_attempt_at) für Retry-Worker.

WebhookDeliveryAttempt

Pro Versuch ein Audit-Eintrag.

  • id, tenant_id, delivery_id, attempted_at
  • attempt_number (1..5)
  • request_signature (HMAC-Hex, gespeichert für Diagnose)
  • response_status_code (Integer, nullable bei Network-Error)
  • response_body_excerpt (max. 500 Zeichen)
  • response_time_ms
  • error_text (Klartext bei Network/Timeout-Fehler)

Retention: 30 Tage.

IncomingWebhookIngestion

Logs der eingehenden Webhooks (Lead-Push, Form-Submissions, etc.). Tenant-scoped.

  • id, tenant_id, received_at
  • slug (z.B. website-form-kontakt — vom Tenant definiert)
  • source_kind (Enum: lead | form_submission | generic_event — Phase 1 only Lead-fokussiert)
  • auth_method (Enum: api_key | hmac_signature | unauthenticated_with_token)
  • payload (JSONB)
  • processing_status (Enum: received | processing | done | failed | rejected_invalid_payload | rejected_auth | rejected_rate_limit)
  • processed_at, error_text
  • derived_lead_id / derived_contact_id (FK, nullable — was wurde erzeugt)
  • client_ip, user_agent

Retention: 90 Tage erfolgreiche, 180 Tage fehlerhafte (für Diagnose).


Block B — Authentifizierung & Scopes

Authentifizierung-Methoden

Methode 1: API-Key-Bearer (Standard)

  • Header: Authorization: Bearer hg_<random_64_chars>
  • API-Key-Verwaltung in M27 Block E
  • Pro Request: Loader prüft Key-Existenz, Scope, Tenant-Zuordnung, Aktiv-Status

Methode 2: HMAC-Signatur (für eingehende Webhooks)

  • Header: X-HiveGrid-Signature: sha256=<hex>
  • Body wird mit Webhook-Slug-Secret HMAC-SHA256 signiert
  • Verifikation mit Constant-Time-Compare gegen Slug-spezifisches Secret

Methode 3: URL-Token (Fallback für Form-Webhooks)

  • URL-Path enthält Token: /api/v1/webhooks/incoming/{tenant}/{slug}?token=...
  • Mit Klartext-Warnung im UI: „URL-Token ist weniger sicher als API-Key — nur für Form-Anbieter ohne Header-Support nutzen"

Scope-Modell (kommt aus M27 Block E, hier konkretisiert)

Scope Erlaubt
read_only Alle GET-Endpoints außer sensible Felder (Mails, HR, finanzielle Daten)
read_full Alle GET-Endpoints inkl. sensible Daten
webhook_inbound Eingehende Lead-/Form-Webhook-Endpoints — kein Read-Zugriff
automation_trigger Auslösen von Automation-Triggern via API

Scope-Mapping zu Endpoints

  • Default Phase 1: 1 Key = 1 Scope
  • Phase 2: Multi-Scope-Keys + granulare Scopes pro Modul

Klartext-Fehler

  • 401 unauthorized: „API-Key fehlt oder ungültig. Header Authorization: Bearer hg_... setzen."
  • 403 forbidden: „Dieser API-Key hat nicht die Berechtigung für diese Aktion. Erforderlicher Scope: read_full."
  • 429 rate limit: „Rate-Limit erreicht: 1.000 Anfragen/Stunde. Reset um [timestamp]. Tenant-Admin kann Limit erhöhen."

Block C — Read-API (GET-Endpoints)

Endpoint-Übersicht

GET  /api/v1/contacts                   → Liste Kontakte
GET  /api/v1/contacts/:id               → Einzelner Kontakt
GET  /api/v1/companies                  → Liste Firmen
GET  /api/v1/companies/:id              → Einzelne Firma
GET  /api/v1/deals                      → Liste Deals
GET  /api/v1/deals/:id                  → Einzelner Deal
GET  /api/v1/projects                   → Liste Projekte
GET  /api/v1/projects/:id               → Einzelnes Projekt
GET  /api/v1/tasks                      → Liste Tasks
GET  /api/v1/tasks/:id                  → Einzelner Task
GET  /api/v1/leads                      → Liste Leads
GET  /api/v1/leads/:id                  → Einzelner Lead

Gemeinsame Konventionen

Pagination (Cursor-basiert):

  • Query-Param cursor (opaque, base64-encoded)
  • Query-Param limit (Default 50, max. 200)
  • Response enthält meta.next_cursor (null wenn keine weiteren)

Filter:

  • Per Query-Param, z.B. ?tag=newsletter&assignee_id=...
  • Multi-Value: ?tag=a&tag=b (OR-Logik)
  • Date-Range: ?created_at_gte=2026-01-01&created_at_lte=2026-12-31
  • Custom-Felder: ?custom.heizungsanlage_modell=Vaillant

Sortierung:

  • Query-Param sort (z.B. sort=-updated_at für absteigend, sort=last_name für aufsteigend)
  • Default pro Endpoint dokumentiert

Field-Selection (Sparse Fieldsets):

  • Query-Param fields (z.B. ?fields=id,first_name,last_name,emails)
  • Reduziert Payload bei großen Listen

Embed Relations:

  • Query-Param embed (z.B. ?embed=primary_company,assigned_to)
  • Default: nur IDs der Verknüpfungen
  • Mit Embed: vollständige Sub-Objekte
  • Tiefe max. 1 (kein verschachteltes Embedding in Phase 1)

Response-Format

Erfolg:

{
  "data": { ... } oder [...],
  "meta": {
    "next_cursor": "...",
    "total_count_estimate": 1234
  }
}

Fehler:

{
  "error": {
    "code": "validation_failed",
    "message": "Klartext-Fehler-Beschreibung",
    "details": { "field": "explanation" }
  }
}

Endpoint-Details (Beispiel: GET /api/v1/contacts)

Filter:

  • tag (Multi)
  • assignee_id
  • lead_source
  • is_endkunde
  • language
  • created_at_gte, created_at_lte, updated_at_gte, updated_at_lte
  • q (Volltext über Name/Email/Phone/Notes)
  • archived (Boolean — Default false)
  • custom.{field_key} (für Custom-Felder, dynamisch validiert)

Sortierung:

  • last_name, first_name, created_at, updated_at, last_activity_at
  • Default: -last_activity_at

Embed-Optionen:

  • primary_company, assigned_to, tags, emails, phones, custom_fields

Sensible Felder (nur mit read_full-Scope):

  • notes
  • custom_fields mit is_sensitive=true (z.B. HR-Personalnummer in Phase 2)
  • Activities

Endpoint-Details (Beispiel: GET /api/v1/deals)

Filter: pipeline_id, stage_id, assignee_id, tag, value_gte, value_lte, state (open|won|lost), contact_id, company_id, created_at_*, updated_at_*

Sortierung: created_at, updated_at, value, expected_close_date, last_activity_at — Default: -last_activity_at

Embed: pipeline, stage, primary_contact, primary_company, assigned_to, tags

Permissions-aware-Default (AV #5)

  • Endpoints filtern automatisch nach Scope
  • Sensible Felder werden bei read_only aus Response entfernt (nicht 403, sondern Feld-Auslassung mit Hinweis im OpenAPI-Schema)

Block D — Eingehende Webhooks (Lead-Push)

Endpoint

POST /api/v1/webhooks/incoming/{tenant_slug}/{webhook_slug}

Webhook-Slug-Verwaltung

Verwaltung in /{tenant}/admin/api-keys/incoming-webhooks/ (gemeinsam mit API-Keys aus M27).

Felder pro Slug:

  • slug (Tenant-eindeutig, z.B. website-kontaktformular)
  • purpose (Enum: lead | form_submission | generic_event — Phase 1: meist lead)
  • auth_method (Enum: api_key | hmac_signature | url_token)
  • secret_or_token_encrypted
  • payload_mapping (JSONB — Mapping von Webhook-Field zu HiveGrid-Field)
  • default_assignee_id (FK, optional)
  • default_tags[]
  • auto_promote_to_contact (Boolean — sofort als Contact statt Lead anlegen, Default false)
  • is_active, archived_at

Standard-Payload-Format (Lead-Push)

Tenant kann eigenes Mapping definieren, aber Default-Schema für direkten POST:

{
  "first_name": "Max",
  "last_name": "Mustermann",
  "email": "max@example.de",
  "phone": "+491234567890",
  "message": "Anfrage zur Wartung",
  "source_label": "Website-Form",
  "metadata": { ...beliebige Felder... }
}

Verarbeitung

  1. Auth verifizieren (Methode aus Slug-Config)
  2. Rate-Limit prüfen (siehe Block H)
  3. Payload validieren (gegen payload_mapping)
  4. IncomingWebhookIngestion mit processing_status=processing anlegen
  5. Lead anlegen (Modul 2) mit Mapped-Werten + Source = Slug
  6. Auto-Match-Versuch: existiert Contact mit selber Email? → falls ja, Activity am Contact statt neuem Lead (oder konfigurierbar pro Slug)
  7. Auto-Tag aus default_tags
  8. processing_status=done, derived_lead_id gesetzt
  9. Response: 201 Created mit { "id": "...", "kind": "lead" }

Fehler-Pfade

  • Ungültiges Payload: 400 Bad Request mit Klartext-Validation-Errors
  • Auth-Fehler: 401 Unauthorized mit Klartext
  • Slug nicht gefunden / inactive: 404 Not Found
  • Rate-Limit: 429
  • Tenant in frozen-Status: 403 Forbidden mit Klartext: „Workspace ist pausiert — eingehende Webhooks werden aktuell verworfen."
  • Server-Fehler: 500 + Eintrag in IncomingWebhookIngestion.processing_status=failed für Debugging

Klartext-Hinweise im Tenant-UI

  • Slug-Detail-View zeigt: letzte 100 Ingestion-Events mit Status, Fehler-Klartext, Replay-Button (Phase 2)
  • „Webhook-Slug website-form hat in den letzten 24h: 47 Erfolge, 2 Fehler. [Logs anzeigen]"

Block E — Ausgehende Webhooks

Subscription-Verwaltung in /{tenant}/admin/webhooks/

Felder pro Subscription:

  • name (interner Name)
  • target_url
  • secret (HMAC-Sign — System-generiert, einmalig sichtbar bei Anlage)
  • event_types[] (Multi-Select aus verfügbaren Events)
  • filter_definition (optional)

Verfügbare Event-Types (Phase 1)

contact.created
contact.updated
contact.archived
contact.deleted
contact.tag_added
contact.tag_removed

company.created
company.updated
company.archived

lead.created
lead.qualified
lead.converted
lead.lost
lead.spam

deal.created
deal.stage_changed
deal.won
deal.lost
deal.archived

project.created
project.stage_changed
project.completed
project.archived

task.created
task.completed
task.assigned

email.received
email.sent
email.bounced

call.completed
call.missed

Event-Payload-Format

{
  "event_id": "evt_...",         // unique pro Event-Auslösung, für Idempotenz
  "event_type": "contact.created",
  "tenant_id": "...",
  "tenant_slug": "geerkens",
  "occurred_at": "2026-05-08T10:23:00Z",
  "data": { /* vollständiges Entity-Objekt analog zu GET /api/v1/<entity>/:id */ },
  "previous_data": { /* nur bei *.updated/*_changed — vorheriger Zustand */ }
}

Signatur

  • Header X-HiveGrid-Signature: sha256=<hex> mit HMAC-SHA256(secret, body)
  • Header X-HiveGrid-Event: contact.created
  • Header X-HiveGrid-Event-Id: evt_... (für Idempotenz)
  • Empfänger soll Signatur verifizieren + bei Idempotenz-Konflikt 200 OK ohne Re-Processing antworten

Retry-Strategie

  • Bei Response 2xx: delivered
  • Bei 4xx (außer 408/429): failed, kein Retry — Klartext: „Endpoint hat 4xx geantwortet — möglicherweise falsch konfiguriert. Subscription bleibt aktiv."
  • Bei 5xx, 408, 429, Network/Timeout: Retry mit exponentiellem Backoff (1min, 5min, 30min, 2h, 12h) — max. 5 Versuche
  • Nach 5 Versuchen: exhausted, failure_count_consecutive inkrementiert
  • Bei failure_count_consecutive >= 10: Subscription auto-deaktiviert (is_active=false) mit Klartext-Notification: „Webhook ‚[Name]' wurde nach 10 fehlgeschlagenen Auslieferungen deaktiviert. [Reaktivieren]"

Delivery-Stats in Subscription-Detail-View

  • Letzte 100 Deliveries mit Status, Response-Code, Response-Excerpt
  • Aggregat: „Letzte 7 Tage: 234 Deliveries, 230 erfolgreich (98.3%)"
  • Replay-Button pro fehlgeschlagener Delivery (manueller Re-Versuch)
  • Test-Funktion: „Test-Event senden" — sendet Sample-Payload mit event_type=test.ping

Permission

  • Subscription-Verwaltung: tenant.admin ODER integrations.admin
  • Auslösung: System-Actor

Block F — Allgemeine Event-Ingestion

Endpoint

POST /api/v1/integrations/events

Generischer Ingest für externe Systeme, die Custom-Events pushen wollen (z.B. eigenes ERP pushed Status-Update).

Auth

  • API-Key mit Scope automation_trigger (oder webhook_inbound)

Payload

{
  "event_type": "external.deal_status_changed",
  "external_id": "deal-12345",
  "data": { ... }
}

Verarbeitung

  • Event landet in Automation-Engine (M17) als Trigger external_event
  • Event-Filter pro Automation: event_type Match
  • Phase 1: nur als Trigger (keine direkte Datenmanipulation)
  • Phase 2: Event-Mapping zu CRM-Updates

Block G — OpenAPI-Doku

Auto-Generierung

  • OpenAPI-3.1-Spec generiert aus Code (Zod-Schemas oder ähnlich)
  • Endpoint: /api/v1/openapi.json
  • Includiert: alle Endpoints, Request-/Response-Schemas, Auth-Methoden, Beispiele

Swagger-UI

  • Endpoint: /swagger
  • Öffentlich zugänglich (nicht Tenant-spezifisch)
  • „Try it out"-Funktion mit API-Key-Eingabe-Feld
  • Beispiel-Requests für alle Endpoints

Klartext-Beschreibungen

  • Jeder Endpoint hat Klartext-Description in OpenAPI
  • Field-Level-Descriptions für nicht-offensichtliche Felder
  • Pflicht-Felder vs. Optional klar markiert

Tenant-spezifische Doku-Hinweise

  • In /{tenant}/admin/api-keys/ Verlinkung zu Swagger mit Hinweis: „Verwende deinen API-Key oben rechts in Swagger zum Testen"

Block H — Rate-Limiting

Limits (Phase 1)

  • Default pro API-Key: 1.000 Requests/Stunde (rolling)
  • Burst: kurzfristig 50 Requests/Sekunde tolerabel
  • Pro Tenant aggregiert: 10.000 Requests/Stunde
  • Eingehende Webhooks pro Slug: 100 Requests/Minute
  • Tenant-Admin kann Limit pro Key erhöhen (max. 10.000/h ohne Plattform-Admin-Approval)

Implementation

  • Token-Bucket-Algorithmus
  • Counter in Redis pro Key + pro Tenant
  • Headers in jeder Response:
    • X-RateLimit-Limit: 1000
    • X-RateLimit-Remaining: 873
    • X-RateLimit-Reset: 1715169600 (Unix-Timestamp)
  • Bei Überschreitung: 429 + Retry-After-Header

Klartext-429-Body

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate-Limit erreicht: 1.000 Anfragen/Stunde. Limit setzt sich um [timestamp] zurück.",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_at": "2026-05-08T11:00:00Z",
      "tenant_admin_can_increase": true
    }
  }
}

Metering für Phase 2

  • Aggregat-Stats in /{tenant}/admin/api-keys/{id}/usage/: Tagesverbrauch, Top-Endpoints, Fehler-Rate
  • Phase 2: Pricing-relevante Über-Limits (Cloud+ erlaubt mehr Requests)

Block I — Versionierung & Stabilität

URL-basierte Versionierung

  • Aktuelle Version: v1
  • Pfad: /api/v1/...
  • Major-Bump (v2) nur bei Breaking Changes

Backwards-Compatibility-Regeln (Phase 1)

  • Neue Felder hinzufügen: erlaubt
  • Felder entfernen: nur mit Deprecation-Phase + neuer Version
  • Field-Type ändern: nur mit neuer Version
  • Pflicht-Filter hinzufügen: nur mit neuer Version

Deprecation-Header

  • Endpoints im Sunset-Pfad senden Sunset: <date> und Deprecation: true Header
  • Klartext-Hinweis in OpenAPI-Description

Stability-Tags pro Endpoint

  • stable (Phase 1: alle Read-Endpoints)
  • experimental (Phase 2-Vorboten — Kein SLA)
  • deprecated (Sunset angekündigt)

Block J — Permissions / Scope-Mapping

Scope-Mapping zu Endpoints

Endpoint Min. Scope
GET /api/v1/contacts* read_only (sensible Felder ausgeblendet) oder read_full
GET /api/v1/companies* read_only oder read_full
GET /api/v1/deals* read_only oder read_full
GET /api/v1/projects* read_only oder read_full
GET /api/v1/tasks* read_only oder read_full
GET /api/v1/leads* read_only oder read_full
POST /api/v1/webhooks/incoming/* webhook_inbound
POST /api/v1/integrations/events automation_trigger
GET /api/v1/openapi.json unauth
/swagger unauth

Sensible Felder bei read_only

Werden in Response weggelassen (nicht 403, da Endpoint selbst erlaubt ist):

  • Contact.notes
  • Contact.custom_fields[where is_sensitive=true]
  • Deal.notes
  • Project.notes
  • Lead.message

Tenant-Status-Wirkung

  • Tenant frozen / past_due (read-only): GET erlaubt, alle POST/PUT/DELETE → 403 mit Klartext: „Workspace ist im Read-Only-Modus."
  • Tenant suspended / deleted: alle Requests → 403 / 410
  • Tenant deletion_pending: GET erlaubt, POST/PUT/DELETE blockiert

API-Key-Owner-Wirkung

  • API-Keys gehören Tenants, nicht Usern (M27)
  • Bei Anfrage werden RLS-Policies mit app.tenant_id = key.tenant_id gesetzt
  • Kein User-Owner-Check (Keys sehen alle Tenant-Daten ihres Scopes)

Activity-Stream-Integration

Activity-Typen die M34 produziert (Audit)

  • api_key_used (nicht pro Request, sondern bei sicherheitsrelevanten Aktionen — Phase 2)
  • webhook_subscription_created
  • webhook_subscription_disabled (auto bei Failure-Threshold)
  • incoming_webhook_received (nur für processing_status=done mit derived_lead_id → Activity am Lead)

Verknüpfungen

  • Eingehende Webhooks die Leads erzeugen: Activity am Lead mit summary_text: „Lead erzeugt aus Webhook ‚[Slug]' am [Datum]"

Permission-Wirkung

  • Webhook-Subscription-Audits sichtbar mit audit.read
  • API-Request-Logs sichtbar mit tenant.admin oder integrations.admin (in /{tenant}/admin/api-keys/{id}/logs/)

Klartext-Hinweise/-Fehler (Querschnitt)

Auth-Fehler

  • 401 fehlender Header: „API-Key fehlt. Setze Header: Authorization: Bearer hg_<dein_key>"
  • 401 ungültiger Key: „API-Key ist ungültig oder widerrufen."
  • 403 falscher Scope: „Dieser API-Key hat Scope [X], benötigt wird [Y]. Tenant-Admin kann Scope ändern."

Webhook-Fehler

  • Eingehender Webhook mit ungültigem Payload: „Pflichtfeld email fehlt im Payload. Erwartetes Schema: [Link zur Mapping-Doku]"
  • Ausgehender Webhook deaktiviert: „Webhook ‚[Name]' ist nach 10 fehlgeschlagenen Auslieferungen deaktiviert. Letzter Fehler: HTTP 502 vom Endpoint. [Reaktivieren]"

Rate-Limit

  • „Rate-Limit erreicht. Reset um [Zeit]. Tenant-Admin kann Limit erhöhen unter /admin/api-keys/."

Validation

  • „Filter created_at_gte muss ISO-8601 sein, z.B. 2026-01-01 oder 2026-01-01T00:00:00Z. Erhalten: [wert]."

Phase 2 / spätere Features

  • Voll-CRUD-API: POST/PUT/PATCH/DELETE für alle Hauptentitäten
  • GraphQL-Endpoint als zweite Schnittstelle (/api/graphql)
  • OAuth2-Provider-Modus: Drittanbieter-Apps können HiveGrid-Daten im Namen des Users abfragen (3-Legged-OAuth)
  • Granulare Scopes pro Modul-Aktion: z.B. contacts:read, contacts:write, deals:read_all
  • API-Versioning v2 mit Deprecation-Plan für v1
  • Webhook-Replay-Tool in UI (für IncomingWebhookIngestion und WebhookDelivery)
  • Bulk-Export-Endpoint (POST /api/v1/exports → asynchroner Job → S3-Pre-Signed-URL)
  • Filter-Engine als URL-Param (komplexere Filter-Trees per ?filter=... mit JSON)
  • Rate-Limit-Tier-Boost über Pricing-Plan (Cloud+ = 5.000/h)
  • API-Key-Rotation-Workflow (Übergangsfenster mit zwei aktiven Keys)
  • Plattform-Admin-API (admin.hivegrid.de/api/admin/...) für Tenant-Management

Architektur-Vorschriften (Querschnitt)

  • LP-6 Anti-Agentur: API soll für Noah und „dummen Handwerker" pflegbar sein → klare Klartext-Fehler, Swagger-UI mit Try-it-out
  • LP-9: Requirements-pur, kein Layout
  • LP-10: Klartext-Diagnose bei jedem 4xx/5xx
  • LP-11: Webhook-Subscriptions sind selbst Adapter-konform — externe Tools können sich anschließen ohne Code-Änderung in HiveGrid
  • LP-13: API-Endpoints laufen auf EU-Servern, Logs in EU-DB
  • AV #5 Permissions-aware-Default: Sensible Felder werden bei read_only automatisch weggelassen
  • AV #6 Audit-Trail: API-Key-Anlage, Webhook-Setup, alle Lead-Inbound-Events geloggt

Detail-Spec-Status: DRAFT

Erste vollständige Detail-Spec für Modul 34. Phase-1-Basic, bewusst Read-only + Webhooks. Vor Bau: OpenAPI-Tooling-Auswahl (Zod-zu-OpenAPI vs. tRPC-OpenAPI vs. manuell), Rate-Limiter-Implementierung mit Redis testen, HMAC-Signatur-Format dokumentieren.

Offene Detail-Punkte (nicht-blockierend):

  • Konkrete Field-Mapping-DSL für Incoming-Webhooks (Phase 1 möglicherweise nur 1:1, Phase 2 mit Transform-Functions)
  • Konkretes Default-Tenant-API-Aggregat-Limit (10.000/h vorgeschlagen — final mit Performance-Tests)
  • OpenAPI-Hosting-URL (eigene Subdomain developers.hivegrid.de vs. /swagger auf app-Domain)
  • Subframe-UI-Designs für API-Key-Verwaltung und Webhook-Subscription-View (separat — kommt aus M27)
  • Verknüpfung mit Modul 17 Automation-Engine für external_event-Trigger-Pfad