Kapitel 13 Clients, Groupware & CLI Admin: #pApiAuth

Scoped API-Keys, Transaktionale Sende-API (/api/v1/send), IP-Warming, SCIM 2.0 & OIDC

Shops, Ticketsysteme, ERP-Lösungen und CI/CD-Pipelines sollten niemals das persönliche Passwort eines Mitarbeiters mitbenutzen. Unter API-Keys, SSO & Regeln (#pApiAuth) erstellst du rollen- und IP-beschränkte Scoped API-Schlüssel (smk_...), versendest Transaktions-Mails mit kategoriebasiertem IP-Warming über POST /api/v1/send und bindest OIDC/SCIM 2.0 an.

Praxis-Tipp & Architektur-Hinweis

Wichtig für 2FA & Least Privilege: Konten mit aktivierter Zwei-Faktor-Authentifizierung blockieren einfache HTTP-Basic-Passwort-Logins an /api/admin/* automatisch. Erstelle für Webshops stets einen Schlüssel mit Role = User (darf ausschließlich über /api/v1/send ab der freigegebenen Absenderadresse senden) und für nextxch-cli / Ansible einen CIDR-geschützten TenantAdmin- oder ServerAdmin-Schlüssel (siehe Kapitel 11: /docs/cli/).

Transaktionale Sende-API (POST /api/v1/send) mit Kategorie & Idempotency-Key

Übergib Bearer smk_... (oder X-Api-Key), eine E-Mail-Kategorie für das Anbieter-Kontingent sowie einen Idempotency-Key gegen doppelte Zustellung bei Netzwerk-Retries.

Referenz / Konfiguration

curl -fsS -X POST "https://mail.firma.de/api/v1/send" \
  -H "Authorization: Bearer smk_01968f2a_..." \
  -H "Idempotency-Key: inv-2026-90412" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "rechnung@firma.de",
    "to": ["kunde@beispiel.de"],
    "subject": "Ihre Rechnung RE-2026-90412",
    "category": "transactional",
    "textBody": "Guten Tag,\nanbei erhalten Sie Ihre Rechnung RE-2026-90412.",
    "htmlBody": "<p>Guten Tag,</p><p>anbei erhalten Sie Ihre Rechnung <strong>RE-2026-90412</strong>.</p>",
    "attachments": [
      {
        "fileName": "RE-2026-90412.pdf",
        "contentType": "application/pdf",
        "base64Content": "JVBERi0xLjcKJ..."
      }
    ]
  }'

# Risikofreier Integrationstest ohne echten Internet-Versand (Sandbox-Sink):
# Empfänger ok@sink.nextxch.local, bounce@sink.nextxch.local, defer@sink.nextxch.local, complaint@sink.nextxch.local

RBAC-Rollenmatrix für Scoped API-Keys

Jeder API-Key sollte stets die kleinstmögliche Rolle und eine CIDR-Quell-IP-Einschränkung erhalten.

Referenz / Konfiguration

Role = User               -> Darf NUR POST /api/v1/send für freigegebene Absenderadressen nutzen (ideal für Shop, CRM, Website)
Role = ComplianceAuditor  -> Schreibgeschützter Zugriff auf Schema, DNS-Prüfung, GoBD-Archiv & Verfahrensdokumentation
Role = TenantAdmin        -> Verwaltet Domains, Konten, Verteiler, Aliase & API-Keys ausschließlich im eigenen Mandanten + SCIM 2.0
Role = ServerAdmin        -> Vollzugriff inkl. Tenants, Route, SpamGuard, SmtpQueue, TransportRules & snapshot --include-secrets

Einstellungen, Standardwerte & Best Practices

Einstellung / Ort	Funktion	Standardwert	Best Practice im Betrieb
`Scoped API-Keys (smk_<id>_<secret>)`	Rollenbasierte Bearer- / X-Api-Key-Schlüssel mit gehashtem Geheimnis, RBAC-Scope (User, ComplianceAuditor, TenantAdmin, ServerAdmin), Standard-E-Mail-Kategorie, CIDR-IP-Allowlist und Ablaufdatum.	`Role = User (Least Privilege)`	Für Shops/ERP Role = User (nur /api/v1/send) mit passender Standard-Kategorie (critical für Login/2FA, transactional für Rechnungen) wählen; für CI/CD Role = TenantAdmin oder ServerAdmin mit CIDR und 90 Tagen Laufzeit vergeben.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Steuert separate Stunden- und Tages-Kontingente pro E-Mail-Kategorie (critical, transactional, notification, marketing) klar getrennt nach Empfänger-Anbieter (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) sowie isoliert je einzelner Ziel-Domain (*).	`28-Tage IP-Warming / 100 % Produktion`	Bei neuen Server-IPs das 28-Tage-IP-Warming aktivieren (5 % -> 100 %): Kritische 2FA-Mails umgehen das Warming sofort (BypassWarming + Priorität 10), während Benachrichtigungen und Marketing-Mails sanft über künftige Stundenfenster gepaced werden (DeferQueue) oder per HTTP 429 + Retry-After rückmelden.
`Idempotency-Key & Response-Header`	Verhindert doppelte E-Mail-Zustellungen bei HTTP-Timeouts und liefert X-RateLimit-Remaining sowie bei OverflowAction = Reject429 ein präzises Retry-After zurück.	`24h Deduplizierungs-Fenster`	Beim Rechnungs- oder Bestellversand die eindeutige Belegnummer (z. B. inv-2026-90412) als Idempotency-Key mitsenden.
`REST Management-Endpunkte (/api/admin/cli/*)`	Offene JSON-/NDJSON-Schnittstelle hinter nextxch-cli (/schema, /objects/{type}, /dns/{domain}, /snapshot, /apply) für eigene Integrationen in C#, Go, Python oder Terraform.	`Bearer smk_... Auth`	Für eigene Provisionierungs-Portale direkt POST /api/admin/cli/objects/Account/User mit einem CIDR-beschränkten TenantAdmin-Key aufrufen.
`Globale Pflicht-Signatur / Disclaimer`	Fügt ausgehenden E-Mails automatisch das gesetzliche Unternehmens-Impressum (HGB / GmbHG) vor der DKIM-Signatur im HTML- und Text-Teil an (inkl. Duplikatschutz).	`Optional aktivierbar`	Sowohl HTML- als auch Reintext-Variante hinterlegen und den Duplikatschutz aktiviert lassen, damit Antwortketten sauber bleiben.
`OIDC Single Sign-On & SCIM 2.0`	Bindet Microsoft Entra ID, Keycloak, Authentik oder Okta für passwortloses Webmail-SSO sowie automatische Benutzer-Provisionierung (/scim/v2) an.	`Lokale Auth + Passkeys aktiv`	Für maximale Sicherheit WebAuthn Passkeys (FIDO2) aktivieren; für SCIM 2.0 einen Scoped API-Key mit Rolle TenantAdmin und CIDR-Filter des IdP nutzen.