Capitolo 15 Client, groupware & CLI Admin: #pApiAuth

Chiavi API con ambito definito, Transactional Send API (/api/v1/send), IP warming, SCIM 2.0 & OIDC

App web, strumenti di ticketing, sistemi ERP e pipeline CI/CD non dovrebbero mai condividere le password delle caselle di posta delle persone. In API Keys, SSO & Rules (#pApiAuth) si generano chiavi API con ambito limitate per CIDR (smk_...), si invia posta transazionale categorizzata tramite POST /api/v1/send con warming IP automatico e si collegano OIDC/SCIM 2.0.

Suggerimento operativo & nota sull'architettura

Regola 2FA & privilegio minimo: gli account con 2FA attivata rifiutano automaticamente i semplici login HTTP Basic con password su /api/admin/*. Generare sempre chiavi con Role = User per app web/ERP (limitate rigorosamente a /api/v1/send dal loro indirizzo mittente autorizzato) e chiavi TenantAdmin/ServerAdmin vincolate per CIDR per l'automazione con nextxch-cli (vedere il capitolo 13: /docs/cli/).

Transactional Send API (POST /api/v1/send) con categoria & Idempotency-Key

Passare Bearer smk_... (o X-Api-Key), una categoria di messaggio per la gestione delle quote dei provider e un Idempotency-Key per evitare invii duplicati in caso di nuovi tentativi di rete.

Riferimento / configurazione

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

Matrice dei ruoli RBAC per le chiavi API con ambito

Assegnare sempre l'ambito RBAC più ristretto e l'elenco consentiti CIDR di origine necessario per ciascun carico di lavoro.

Riferimento / configurazione

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

Impostazioni, valori predefiniti e best practice

Impostazione / posizione	Descrizione	Valore predefinito	Best practice per la produzione
`Scoped API-Keys (smk_<id>_<secret>)`	Credenziali Bearer / X-Api-Key a privilegio minimo con segreti hashati, ambiti RBAC (User, ComplianceAuditor, TenantAdmin, ServerAdmin), categoria di messaggio predefinita, elenchi consentiti di IP sorgente CIDR e scadenza.	`Role = User (Least Privilege)`	Selezionare Role = User (solo /api/v1/send) con una categoria predefinita esplicita (critical per la 2FA, transactional per le fatture); per CI/CD & Ansible selezionare chiavi TenantAdmin o ServerAdmin limitate per CIDR.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Applica quote orarie e giornaliere distinte per categoria di messaggio (critical, transactional, notification, marketing), chiaramente separate per provider del destinatario (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) e per singolo dominio di destinazione (*).	`28-Tage IP-Warming / 100 % Produktion`	Attivare sui nuovi IP la rampa di IP warming di 28 giorni (5% -> 100%): la posta 2FA critica aggira il warming con priorità di coda 10, mentre le notifiche massive e le e-mail di marketing vengono distribuite gradualmente sulle finestre orarie successive (DeferQueue) o falliscono subito con HTTP 429 + Retry-After.
`Idempotency-Key & Response-Header`	Impedisce l'invio duplicato di e-mail in caso di nuovi tentativi HTTP e restituisce X-RateLimit-Remaining e i secondi esatti di Retry-After quando OverflowAction = Reject429.	`24h Deduplizierungs-Fenster`	Passare il proprio ID ordine o fattura deterministico (ad es. inv-2026-90412) nell'header Idempotency-Key a ogni invio transazionale.
`REST Management-Endpunkte (/api/admin/cli/*)`	Interfaccia HTTP JSON/NDJSON pulita alla base di nextxch-cli (/schema, /objects/{type}, /dns/{domain}, /snapshot, /apply) per integrazioni personalizzate in C#, Go, Python o Terraform.	`Bearer smk_... Auth`	Chiamare POST /api/admin/cli/objects/Account/User con una chiave TenantAdmin limitata per CIDR quando si realizzano pannelli di controllo personalizzati per i clienti.
`Globale Pflicht-Signatur / Disclaimer`	Aggiunge automaticamente i piè di pagina aziendali/legali obbligatori prima della firma DKIM nelle parti text/html e text/plain, con protezione dall'accumulo nelle risposte.	`Optional aktivierbar`	Fornire varianti HTML e testo semplice concise e mantenere attiva la soppressione dei duplicati, così le catene di risposte restano pulite.
`OIDC Single Sign-On & SCIM 2.0`	Collega Entra ID, Keycloak, Authentik o Okta per il single sign-on OIDC e il provisioning automatizzato del ciclo di vita degli utenti con SCIM 2.0 (/scim/v2).	`Lokale Auth + Passkeys aktiv`	Attivare le passkey FIDO2 per gli accessi interattivi e usare una chiave API TenantAdmin limitata per CIDR per il provisioning SCIM 2.0.