第 15 章客户端、Groupware & CLI 管理：#pApiAuth

限定范围的 API 密钥、事务性发送 API（/api/v1/send）、IP 预热、SCIM 2.0 & OIDC

Web 应用、工单工具、ERP 系统和 CI/CD 流水线绝不应共用人员的邮箱密码。在“API 密钥、SSO & 规则”（#pApiAuth）下，生成受 CIDR 限制的限定范围 API 密钥（smk_...），通过 POST /api/v1/send 发送带分类的事务性邮件并自动进行 IP 预热，同时接入 OIDC/SCIM 2.0。

运维提示与架构说明

2FA & 最小权限规则：启用 2FA 的账户会自动拒绝在 /api/admin/* 上使用纯 HTTP Basic 密码登录。始终为 Web 应用/ERP 签发 Role = User 密钥（严格限制为仅能从其授权发件地址调用 /api/v1/send），并为 nextxch-cli 自动化签发受 CIDR 锁定的 TenantAdmin/ServerAdmin 密钥（参见第 13 章：/docs/cli/）。

带 Category & Idempotency-Key 的事务性发送 API（POST /api/v1/send）

传入 Bearer smk_...（或 X-Api-Key）、用于服务商配额管控的邮件类别，以及 Idempotency-Key，以防网络重试时重复发送。

参考 / 配置

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

作用域 API 密钥的 RBAC 角色矩阵

始终为每个工作负载分配所需的最小 RBAC 范围和来源 CIDR 允许列表。

参考 / 配置

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

设置、默认值与最佳实践

设置 / 位置	说明	默认值	生产环境最佳实践
`Scoped API-Keys (smk_<id>_<secret>)`	最小权限的 Bearer / X-Api-Key 凭据，采用哈希存储的机密、RBAC 范围（User、ComplianceAuditor、TenantAdmin、ServerAdmin）、默认邮件类别、CIDR 源 IP 允许列表以及过期时间。	`Role = User (Least Privilege)`	选择 Role = User（仅限 /api/v1/send）并指定明确的默认类别（2FA 用 critical，发票用 transactional）；CI/CD & Ansible 请选择受 CIDR 限制的 TenantAdmin 或 ServerAdmin 密钥。
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	按邮件类别（critical、transactional、notification、marketing）执行不同的每小时和每日配额，并按收件方服务商（Google/Gmail、Microsoft Outlook/Hotmail/Live、Yahoo & AOL、T-Online/GMX/WEB.DE、Apple iCloud）及单个目标域 (*) 清晰区分。	`28-Tage IP-Warming / 100 % Produktion`	在新 IP 上启用 28 天 IP 预热梯度（5% -> 100%）：关键的 2FA 邮件以队列优先级 10 绕过预热，而批量通知和营销邮件则平滑分摊到后续的每小时时间窗口（DeferQueue），或以 HTTP 429 + Retry-After 快速失败。
`Idempotency-Key & Response-Header`	防止 HTTP 重试导致重复提交邮件，并在 OverflowAction = Reject429 时返回 X-RateLimit-Remaining 以及精确的 Retry-After 秒数。	`24h Deduplizierungs-Fenster`	每次发送事务性邮件时，在 Idempotency-Key 请求头中传入确定性的订单号或发票号（例如 inv-2026-90412）。
`REST Management-Endpunkte (/api/admin/cli/*)`	为 nextxch-cli 提供支撑的简洁 JSON/NDJSON HTTP 接口（/schema、/objects/{type}、/dns/{domain}、/snapshot、/apply），可用于 C#、Go、Python 或 Terraform 中的自定义集成。	`Bearer smk_... Auth`	构建自定义客户控制面板时，使用受 CIDR 限制的 TenantAdmin 密钥调用 POST /api/admin/cli/objects/Account/User。
`Globale Pflicht-Signatur / Disclaimer`	在 DKIM 签名之前，自动在 text/html 和 text/plain 部分追加强制性的公司/法律页脚，并防止回复中重复叠加。	`Optional aktivierbar`	提供简洁的 HTML 和纯文本两种版本，并保持重复抑制处于启用状态，使回复链保持整洁。
`OIDC Single Sign-On & SCIM 2.0`	连接 Entra ID、Keycloak、Authentik 或 Okta，实现 OIDC 单点登录，并通过 SCIM 2.0 自动配置用户生命周期 (/scim/v2)。	`Lokale Auth + Passkeys aktiv`	为交互式登录启用 FIDO2 通行密钥，并使用限制 CIDR 的 TenantAdmin API 密钥进行 SCIM 2.0 配置。