Chapitre 15 Clients, groupware & CLI Admin : #pApiAuth

Clés API à portée limitée, Transactional Send API (/api/v1/send), préchauffage d'IP, SCIM 2.0 & OIDC

Les applications web, outils de ticketing, systèmes ERP et pipelines CI/CD ne doivent jamais partager les mots de passe des boîtes aux lettres des utilisateurs. Sous API Keys, SSO & Rules (#pApiAuth), générez des clés API à portée limitée restreintes par CIDR (smk_...), envoyez des e-mails transactionnels catégorisés via POST /api/v1/send avec préchauffage automatique des IP, et connectez OIDC/SCIM 2.0.

Conseil d'exploitation & note d'architecture

Règle 2FA & moindre privilège : les comptes avec 2FA activée rejettent automatiquement les connexions HTTP Basic par simple mot de passe sur /api/admin/*. Émettez toujours des clés Role = User pour les applications web/ERP (limitées strictement à /api/v1/send depuis leur adresse d'expéditeur autorisée) et des clés TenantAdmin/ServerAdmin verrouillées par CIDR pour l'automatisation avec nextxch-cli (voir le chapitre 13 : /docs/cli/).

Transactional Send API (POST /api/v1/send) avec catégorie & Idempotency-Key

Transmettez Bearer smk_... (ou X-Api-Key), une catégorie de message pour la gestion des quotas fournisseur et un Idempotency-Key pour éviter les envois en double lors des nouvelles tentatives réseau.

Référence / configuration

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 des rôles RBAC pour les clés API à portée limitée

Attribuez toujours la portée RBAC la plus restreinte et la liste d'autorisation CIDR source minimale nécessaires à chaque charge de travail.

Référence / configuration

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

Paramètres, valeurs par défaut & bonnes pratiques

Paramètre / emplacement	Description	Valeur par défaut	Bonne pratique en production
`Scoped API-Keys (smk_<id>_<secret>)`	Identifiants Bearer / X-Api-Key à moindre privilège avec secrets hachés, portées RBAC (User, ComplianceAuditor, TenantAdmin, ServerAdmin), catégorie de message par défaut, listes d'autorisation d'IP sources CIDR et expiration.	`Role = User (Least Privilege)`	Choisissez Role = User (/api/v1/send uniquement) avec une catégorie par défaut explicite (critical pour la 2FA, transactional pour les factures) ; choisissez des clés TenantAdmin ou ServerAdmin restreintes par CIDR pour CI/CD & Ansible.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Applique des quotas horaires et journaliers distincts par catégorie de message (critical, transactional, notification, marketing), clairement séparés par fournisseur destinataire (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) et par domaine de destination individuel (*).	`28-Tage IP-Warming / 100 % Produktion`	Activez la montée en charge IP sur 28 jours (5 % -> 100 %) pour les nouvelles IP : les e-mails 2FA critiques contournent la montée en charge avec la priorité de file d'attente 10, tandis que les notifications de masse et les e-mails marketing sont étalés en douceur sur les fenêtres horaires suivantes (DeferQueue) ou échouent immédiatement avec HTTP 429 + Retry-After.
`Idempotency-Key & Response-Header`	Empêche la soumission en double d'e-mails lors de nouvelles tentatives HTTP et renvoie X-RateLimit-Remaining ainsi que le nombre exact de secondes Retry-After lorsque OverflowAction = Reject429.	`24h Deduplizierungs-Fenster`	Transmettez votre identifiant déterministe de commande ou de facture (par ex. inv-2026-90412) dans l'en-tête Idempotency-Key lors de chaque envoi transactionnel.
`REST Management-Endpunkte (/api/admin/cli/*)`	Interface HTTP JSON/NDJSON épurée sur laquelle repose nextxch-cli (/schema, /objects/{type}, /dns/{domain}, /snapshot, /apply) pour des intégrations personnalisées en C#, Go, Python ou Terraform.	`Bearer smk_... Auth`	Appelez POST /api/admin/cli/objects/Account/User avec une clé TenantAdmin restreinte par CIDR lorsque vous créez des panneaux de contrôle clients personnalisés.
`Globale Pflicht-Signatur / Disclaimer`	Ajoute automatiquement les pieds de page obligatoires de l'entreprise/légaux avant la signature DKIM, dans les parties text/html et text/plain, avec anti-empilement dans les réponses.	`Optional aktivierbar`	Fournissez des variantes HTML et texte brut concises et laissez la suppression des doublons activée afin que les fils de réponses restent propres.
`OIDC Single Sign-On & SCIM 2.0`	Connecte Entra ID, Keycloak, Authentik ou Okta pour l'authentification unique OIDC ainsi que le provisionnement automatisé du cycle de vie des utilisateurs via SCIM 2.0 (/scim/v2).	`Lokale Auth + Passkeys aktiv`	Activez les clés d'accès FIDO2 pour les connexions interactives et utilisez une clé API TenantAdmin restreinte par CIDR pour le provisionnement SCIM 2.0.