Capítulo 15 Clientes, groupware & CLI Admin: #pApiAuth

Claves de API con ámbito, Transactional Send API (/api/v1/send), calentamiento de IP, SCIM 2.0 & OIDC

Las aplicaciones web, herramientas de tickets, sistemas ERP y pipelines de CI/CD nunca deben compartir contraseñas de buzones de personas. En API Keys, SSO & Rules (#pApiAuth), genere claves API con ámbito restringidas por CIDR (smk_...), envíe correo transaccional categorizado mediante POST /api/v1/send con calentamiento de IP automático y conecte OIDC/SCIM 2.0.

Consejo operativo y nota de arquitectura

Regla de 2FA & mínimo privilegio: las cuentas con 2FA activada rechazan automáticamente los inicios de sesión con contraseña HTTP Basic simple en /api/admin/*. Emita siempre claves con Role = User para aplicaciones web/ERP (restringidas estrictamente a /api/v1/send desde su dirección de remitente autorizada) y claves TenantAdmin/ServerAdmin bloqueadas por CIDR para la automatización con nextxch-cli (véase el capítulo 13: /docs/cli/).

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

Pase Bearer smk_... (o X-Api-Key), una categoría de mensaje para la gestión de cuotas por proveedor y una Idempotency-Key para evitar envíos duplicados en los reintentos de red.

Referencia / configuración

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

Matriz de roles RBAC para claves de API con ámbito

Asigne siempre el ámbito RBAC más restringido y la lista de permitidos de CIDR de origen que necesite cada carga de trabajo.

Referencia / configuración

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

Configuración, valores predeterminados y buenas prácticas

Ajuste / ubicación	Descripción	Valor predeterminado	Buena práctica de producción
`Scoped API-Keys (smk_<id>_<secret>)`	Credenciales Bearer / X-Api-Key de privilegio mínimo con secretos con hash, ámbitos RBAC (User, ComplianceAuditor, TenantAdmin, ServerAdmin), categoría de mensaje predeterminada, listas de permitidos de IP de origen CIDR y caducidad.	`Role = User (Least Privilege)`	Seleccione Role = User (solo /api/v1/send) con una categoría predeterminada explícita (critical para 2FA, transactional para facturas); seleccione claves TenantAdmin o ServerAdmin restringidas por CIDR para CI/CD & Ansible.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Aplica cuotas horarias y diarias diferenciadas por categoría de mensaje (critical, transactional, notification, marketing), claramente separadas por proveedor del destinatario (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) y por cada dominio de destino (*).	`28-Tage IP-Warming / 100 % Produktion`	Active la rampa de calentamiento de IP de 28 días (5 % -> 100 %) en IP nuevas: el correo crítico de 2FA omite el calentamiento con prioridad de cola 10, mientras que las notificaciones masivas y los correos de marketing se distribuyen de forma gradual en futuras ventanas horarias (DeferQueue) o fallan de inmediato con HTTP 429 + Retry-After.
`Idempotency-Key & Response-Header`	Evita el envío duplicado de correos en reintentos HTTP y devuelve X-RateLimit-Remaining junto con los segundos exactos de Retry-After cuando OverflowAction = Reject429.	`24h Deduplizierungs-Fenster`	Pase su ID de pedido o de factura determinista (p. ej., inv-2026-90412) en el encabezado Idempotency-Key en cada envío transaccional.
`REST Management-Endpunkte (/api/admin/cli/*)`	Interfaz HTTP JSON/NDJSON limpia en la que se basa nextxch-cli (/schema, /objects/{type}, /dns/{domain}, /snapshot, /apply) para integraciones personalizadas en C#, Go, Python o Terraform.	`Bearer smk_... Auth`	Llame a POST /api/admin/cli/objects/Account/User con una clave TenantAdmin restringida por CIDR cuando cree paneles de control personalizados para clientes.
`Globale Pflicht-Signatur / Disclaimer`	Añade automáticamente pies de página corporativos/legales obligatorios antes de la firma DKIM en las partes text/html y text/plain, con protección contra la acumulación en respuestas.	`Optional aktivierbar`	Proporcione variantes HTML y de texto sin formato concisas y mantenga activada la supresión de duplicados para que las cadenas de respuestas se mantengan limpias.
`OIDC Single Sign-On & SCIM 2.0`	Conecta Entra ID, Keycloak, Authentik u Okta para el inicio de sesión único OIDC, además del aprovisionamiento automatizado del ciclo de vida de usuarios con SCIM 2.0 (/scim/v2).	`Lokale Auth + Passkeys aktiv`	Active llaves de acceso FIDO2 para los inicios de sesión interactivos y use una clave de API TenantAdmin restringida por CIDR para el aprovisionamiento SCIM 2.0.