अध्याय 15 क्लाइंट, ग्रुपवेयर & CLI एडमिन: #pApiAuth

स्कोप वाली API कुंजियाँ, ट्रांज़ैक्शनल सेंड API (/api/v1/send), IP वार्मिंग, SCIM 2.0 & OIDC

वेब ऐप्स, टिकटिंग टूल, ERP सिस्टम और CI/CD पाइपलाइन को कभी भी मानव मेलबॉक्स पासवर्ड साझा नहीं करने चाहिए। API Keys, SSO & Rules (#pApiAuth) के अंतर्गत CIDR-प्रतिबंधित, सीमित दायरे वाली API कुंजियाँ (smk_...) बनाएँ, स्वचालित IP वार्मिंग के साथ POST /api/v1/send के माध्यम से श्रेणीबद्ध ट्रांज़ैक्शनल मेल भेजें और OIDC/SCIM 2.0 कनेक्ट करें।

संचालन सुझाव और आर्किटेक्चर नोट

2FA & न्यूनतम-विशेषाधिकार नियम: 2FA सक्षम खाते /api/admin/* पर केवल HTTP Basic पासवर्ड लॉगिन को स्वचालित रूप से अस्वीकार करते हैं। वेब ऐप्स/ERP के लिए हमेशा Role = User कुंजियाँ बनाएँ (उनके अधिकृत प्रेषक पते से केवल /api/v1/send तक सख्ती से सीमित) और nextxch-cli स्वचालन के लिए CIDR-लॉक्ड TenantAdmin/ServerAdmin कुंजियाँ (अध्याय 13 देखें: /docs/cli/)।

श्रेणी & 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>)`	हैश किए गए सीक्रेट, RBAC स्कोप (User, ComplianceAuditor, TenantAdmin, ServerAdmin), डिफ़ॉल्ट संदेश श्रेणी, CIDR स्रोत IP अनुमति सूची और समाप्ति के साथ न्यूनतम-विशेषाधिकार Bearer / X-Api-Key क्रेडेंशियल।	`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 हेडर में अपना निर्धारक ऑर्डर या इनवॉइस ID (उदा. inv-2026-90412) दें।
`REST Management-Endpunkte (/api/admin/cli/*)`	कस्टम एकीकरण के लिए C#, Go, Python या Terraform में nextxch-cli के पीछे का साफ़ JSON/NDJSON HTTP इंटरफ़ेस (/schema, /objects/{type}, /dns/{domain}, /snapshot, /apply)।	`Bearer smk_... Auth`	कस्टम ग्राहक कंट्रोल पैनल बनाते समय CIDR-प्रतिबंधित TenantAdmin कुंजी के साथ POST /api/admin/cli/objects/Account/User कॉल करें।
`Globale Pflicht-Signatur / Disclaimer`	DKIM हस्ताक्षर से पहले text/html और text/plain भागों में अनिवार्य कॉर्पोरेट/कानूनी फ़ुटर स्वचालित रूप से जोड़ता है, उत्तरों में दोहराव-रोधी सुरक्षा के साथ।	`Optional aktivierbar`	संक्षिप्त HTML और Plaintext संस्करण दें और डुप्लिकेट सप्रेशन सक्षम रखें, ताकि उत्तर शृंखलाएँ साफ़ रहें।
`OIDC Single Sign-On & SCIM 2.0`	OIDC सिंगल साइन-ऑन और स्वचालित SCIM 2.0 उपयोगकर्ता जीवनचक्र प्रोविज़निंग (/scim/v2) के लिए Entra ID, Keycloak, Authentik या Okta को कनेक्ट करता है।	`Lokale Auth + Passkeys aktiv`	इंटरैक्टिव लॉगिन के लिए FIDO2 पासकी सक्षम करें और SCIM 2.0 प्रोविज़निंग के लिए CIDR-प्रतिबंधित TenantAdmin API कुंजी का उपयोग करें।