الفصل 15 العملاء والعمل الجماعي وCLI المسؤول: #pApiAuth

مفاتيح API محددة النطاق، وTransactional Send API (/api/v1/send)، وإحماء IP، وSCIM 2.0 وOIDC

يجب ألا تتشارك تطبيقات الويب وأدوات التذاكر وأنظمة ERP وخطوط CI/CD أبدًا كلمات مرور صناديق البريد البشرية. ضمن API Keys, SSO & Rules (#pApiAuth)، أنشئوا مفاتيح API محددة النطاق ومقيّدة بـ CIDR (smk_...)، وأرسلوا بريدًا معاملاتيًا مصنّفًا عبر POST /api/v1/send مع إحماء IP تلقائي، واربطوا OIDC/SCIM 2.0.

نصيحة تشغيلية وملاحظة حول البنية

قاعدة 2FA وأقل الامتيازات: ترفض الحسابات المفعّل لديها 2FA تلقائيًا تسجيلات الدخول بكلمة مرور HTTP Basic المجردة على /api/admin/*. أصدروا دائمًا مفاتيح Role = User لتطبيقات الويب وأنظمة ERP (مقصورة بصرامة على /api/v1/send من عنوان المرسل المصرّح لها)، ومفاتيح TenantAdmin/ServerAdmin مقيّدة بنطاقات CIDR لأتمتة nextxch-cli (راجعوا الفصل 13: /docs/cli/).

Transactional Send API (POST /api/v1/send) مع Category وIdempotency-Key

مرّروا 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

مصفوفة أدوار RBAC لمفاتيح API محددة النطاق

عيّنوا دائمًا أضيق نطاق 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 بأقل الصلاحيات مع أسرار مجزّأة (Hashed)، ونطاقات RBAC ‏(User، ComplianceAuditor، TenantAdmin، ServerAdmin)، وفئة رسائل افتراضية، وقوائم سماح لعناوين IP المصدر بصيغة CIDR، وتاريخ انتهاء صلاحية.	`Role = User (Least Privilege)`	اختاروا Role = User (/api/v1/send فقط) مع فئة افتراضية صريحة (critical لـ 2FA، وtransactional للفواتير)؛ واختاروا مفاتيح TenantAdmin أو ServerAdmin المقيّدة بـ CIDR لـ CI/CD وAnsible.
`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 يومًا (5% -> 100%) على عناوين IP الجديدة: يتجاوز بريد 2FA الحرج عملية الإحماء بأولوية قائمة انتظار 10، بينما تُوزَّع الإشعارات الجماعية ورسائل التسويق بسلاسة على نوافذ زمنية ساعية مستقبلية (DeferQueue) أو تفشل فورًا مع HTTP 429 + Retry-After.
`Idempotency-Key & Response-Header`	يمنع الإرسال المكرر لرسائل البريد الإلكتروني عند إعادة محاولات HTTP، ويعيد X-RateLimit-Remaining بالإضافة إلى عدد ثواني Retry-After الدقيق عند ضبط OverflowAction = Reject429.	`24h Deduplizierungs-Fenster`	مرّروا رقم الطلب أو رقم الفاتورة الحتمي لديكم (مثل inv-2026-90412) في ترويسة Idempotency-Key مع كل إرسال للمعاملات.
`REST Management-Endpunkte (/api/admin/cli/*)`	واجهة HTTP نظيفة بصيغة JSON/NDJSON تقوم عليها أداة nextxch-cli (/schema و/objects/{type} و/dns/{domain} و/snapshot و/apply) لعمليات التكامل المخصصة بلغات C# أو Go أو Python أو Terraform.	`Bearer smk_... Auth`	استدعوا POST /api/admin/cli/objects/Account/User بمفتاح TenantAdmin مقيّد بنطاقات CIDR عند بناء لوحات تحكم مخصصة للعملاء.
`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 Single Sign-On، بالإضافة إلى التزويد الآلي لدورة حياة المستخدمين عبر SCIM 2.0 (/scim/v2).	`Lokale Auth + Passkeys aktiv`	فعّلوا مفاتيح مرور FIDO2 لتسجيلات الدخول التفاعلية، واستخدموا مفتاح API من نوع TenantAdmin مقيّدًا بنطاقات CIDR لتزويد SCIM 2.0.