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

Chaves de API com escopo, API de envio transacional (/api/v1/send), aquecimento de IP, SCIM 2.0 & OIDC

Aplicações web, ferramentas de tickets, sistemas ERP e pipelines de CI/CD nunca devem compartilhar senhas de caixas de correio de pessoas. Em Chaves de API, SSO & regras (#pApiAuth), gere chaves de API com escopo restritas por CIDR (smk_...), envie e-mails transacionais categorizados via POST /api/v1/send com aquecimento de IP automático e conecte OIDC/SCIM 2.0.

Dica operacional & nota de arquitetura

Regra de 2FA & privilégio mínimo: contas com 2FA ativado rejeitam automaticamente logins simples com senha via HTTP Basic em /api/admin/*. Sempre gere chaves Role = User para aplicações web/ERPs (restritas estritamente a /api/v1/send a partir do endereço de remetente autorizado) e chaves TenantAdmin/ServerAdmin bloqueadas por CIDR para a automação com nextxch-cli (veja o Capítulo 13: /docs/cli/).

API de envio transacional (POST /api/v1/send) com categoria & Idempotency-Key

Passe Bearer smk_... (ou X-Api-Key), uma categoria de mensagem para a governança de cotas por provedor e uma Idempotency-Key para evitar envios duplicados em novas tentativas de rede.

Referência / configuração

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 funções RBAC para chaves de API com escopo

Sempre atribua o escopo RBAC mais restrito e a lista de permissões de CIDR de origem necessária para cada carga de trabalho.

Referência / configuração

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

Configurações, valores padrão e boas práticas

Configuração / local	Descrição	Valor padrão	Boa prática para produção
`Scoped API-Keys (smk_<id>_<secret>)`	Credenciais Bearer / X-Api-Key de privilégio mínimo com segredos em hash, escopos RBAC (User, ComplianceAuditor, TenantAdmin, ServerAdmin), categoria de mensagem padrão, listas de permissões de IP de origem por CIDR e expiração.	`Role = User (Least Privilege)`	Selecione Role = User (somente /api/v1/send) com uma categoria padrão explícita (critical para 2FA, transactional para faturas); selecione chaves TenantAdmin ou ServerAdmin restritas por CIDR para CI/CD & Ansible.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Aplica cotas horárias e diárias distintas por categoria de mensagem (critical, transactional, notification, marketing), claramente separadas por provedor do destinatário (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) e por domínio de destino individual (*).	`28-Tage IP-Warming / 100 % Produktion`	Ative a rampa de aquecimento de IP de 28 dias (5% -> 100%) em IPs novos: e-mails críticos de 2FA ignoram o aquecimento com prioridade de fila 10, enquanto notificações em massa e e-mails de marketing são distribuídos suavemente em janelas horárias futuras (DeferQueue) ou falham rapidamente com HTTP 429 + Retry-After.
`Idempotency-Key & Response-Header`	Impede o envio duplicado de e-mails em novas tentativas HTTP e retorna X-RateLimit-Remaining mais os segundos exatos de Retry-After quando OverflowAction = Reject429.	`24h Deduplizierungs-Fenster`	Passe seu ID determinístico de pedido ou fatura (por exemplo, inv-2026-90412) no cabeçalho Idempotency-Key em cada envio transacional.
`REST Management-Endpunkte (/api/admin/cli/*)`	Interface HTTP JSON/NDJSON limpa por trás do nextxch-cli (/schema, /objects/{type}, /dns/{domain}, /snapshot, /apply) para integrações próprias em C#, Go, Python ou Terraform.	`Bearer smk_... Auth`	Chame POST /api/admin/cli/objects/Account/User com uma chave TenantAdmin restrita por CIDR ao criar painéis de controle personalizados para clientes.
`Globale Pflicht-Signatur / Disclaimer`	Acrescenta automaticamente rodapés corporativos/legais obrigatórios antes da assinatura DKIM nas partes text/html e text/plain, com proteção contra empilhamento em respostas.	`Optional aktivierbar`	Forneça variantes concisas em HTML e texto simples e mantenha a supressão de duplicatas ativada para que as cadeias de respostas permaneçam limpas.
`OIDC Single Sign-On & SCIM 2.0`	Conecta Entra ID, Keycloak, Authentik ou Okta para Single Sign-On OIDC, além do provisionamento automatizado do ciclo de vida de usuários via SCIM 2.0 (/scim/v2).	`Lokale Auth + Passkeys aktiv`	Ative passkeys FIDO2 para logins interativos e use uma chave de API TenantAdmin restrita por CIDR para o provisionamento SCIM 2.0.