Chapter 13 Clients, Groupware & CLI Admin: #pApiAuth

Scoped API Keys, Transactional Send API (/api/v1/send), IP Warming, SCIM 2.0 & OIDC

Web apps, ticketing tools, ERP systems, and CI/CD pipelines should never share human mailbox passwords. Under API Keys, SSO & Rules (#pApiAuth), mint CIDR-restricted Scoped API Keys (smk_...), send categorized transactional mail via POST /api/v1/send with automatic IP warming, and connect OIDC/SCIM 2.0.

Operational Tip & Architecture Note

2FA & Least-Privilege rule: accounts with 2FA enabled automatically reject bare HTTP Basic password logins on /api/admin/*. Always mint Role = User keys for web apps/ERPs (restricted strictly to /api/v1/send from their authorized sender address) and CIDR-locked TenantAdmin/ServerAdmin keys for nextxch-cli automation (see Chapter 11: /docs/cli/).

Transactional Send API (POST /api/v1/send) with Category & Idempotency-Key

Pass Bearer smk_... (or X-Api-Key), a message category for provider quota governance, and an Idempotency-Key to prevent duplicate sends on network retries.

Reference / 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

RBAC Role Matrix for Scoped API Keys

Always assign the narrowest RBAC scope and source CIDR allowlist required for each workload.

Reference / 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

Settings, Default Values & Best Practices

Setting / Location	Description	Default Value	Production Best Practice
`Scoped API-Keys (smk_<id>_<secret>)`	Least-privilege Bearer / X-Api-Key credentials with hashed secrets, RBAC scopes (User, ComplianceAuditor, TenantAdmin, ServerAdmin), default message category, CIDR source IP allowlists, and expiration.	`Role = User (Least Privilege)`	Select Role = User (/api/v1/send only) with an explicit default category (critical for 2FA, transactional for invoices); select CIDR-restricted TenantAdmin or ServerAdmin keys for CI/CD & Ansible.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Enforces distinct hourly and daily quotas per message category (critical, transactional, notification, marketing) clearly separated by recipient provider (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) and per individual destination domain (*).	`28-Tage IP-Warming / 100 % Produktion`	Enable the 28-day IP warming ramp (5% -> 100%) on fresh IPs: critical 2FA mail bypasses warming at queue priority 10, while bulk notifications and marketing emails smoothly pace across future hourly windows (DeferQueue) or fail fast with HTTP 429 + Retry-After.
`Idempotency-Key & Response-Header`	Prevents duplicate email submission across HTTP retries and returns X-RateLimit-Remaining plus exact Retry-After seconds when OverflowAction = Reject429.	`24h Deduplizierungs-Fenster`	Pass your deterministic order or invoice ID (e.g. inv-2026-90412) in the Idempotency-Key header on every transactional send.
`REST Management-Endpunkte (/api/admin/cli/*)`	Clean JSON/NDJSON HTTP interface backing nextxch-cli (/schema, /objects/{type}, /dns/{domain}, /snapshot, /apply) for custom integrations in C#, Go, Python, or Terraform.	`Bearer smk_... Auth`	Call POST /api/admin/cli/objects/Account/User with a CIDR-restricted TenantAdmin key when building custom customer control panels.
`Globale Pflicht-Signatur / Disclaimer`	Automatically appends mandatory corporate/legal footers prior to DKIM signing across text/html and text/plain parts with reply anti-stacking.	`Optional aktivierbar`	Provide concise HTML and Plaintext variants and keep duplicate suppression enabled so reply chains stay clean.
`OIDC Single Sign-On & SCIM 2.0`	Connects Entra ID, Keycloak, Authentik, or Okta for OIDC Single Sign-On plus automated SCIM 2.0 user lifecycle provisioning (/scim/v2).	`Lokale Auth + Passkeys aktiv`	Enable FIDO2 Passkeys for interactive logins and use a CIDR-restricted TenantAdmin API key for SCIM 2.0 provisioning.