Integrações/Fundamentos
Autenticação comum
Os endpoints de integração sob /api/v1/* aceitam a API Key do tenant num de dois cabeçalhos equivalentes:
x-api-key: <tenant-api-key>
Authorization: Bearer <tenant-api-key>
Há dois tipos de chave, ambos em Definições → Integrações:
| Tipo | Âmbito | Validade |
|---|---|---|
| API Key do tenant (única) | Acesso total às rotas /api/v1/* |
Tem data de expiração; chaves antigas sem data são rejeitadas e têm de ser regeneradas |
| Chave API por integração (nomeada) | Uma por servidor ou integração; opcionalmente limitada a rotas (scopes) | 365 dias; revogável individualmente, com efeito imediato; máximo de 20 ativas por tenant |
Boas práticas:
- Uma chave nomeada por integração, com o scope mínimo. Um scope é um prefixo de rota:
/api/v1/monitoring/backup-reportsó abre essa rota (e as que estiverem por baixo dela);/api/v1/assetsnão abre/api/v1/assets-export. Sem scopes a chave tem acesso total, como a API Key única. Fora do scope a resposta é401. - A chave só é mostrada uma vez, na criação (o EterShield guarda apenas o hash). Se se perder, revoga-se e cria-se outra.
- Uma chave expirada, revogada ou de um tenant inativo é rejeitada com
401. - Guardar a chave no cofre de segredos do sistema que a usa, nunca em ficheiros versionados.
Exceções à regra acima:
- Ingestão de SIEM/IDS (Wazuh findings, agents e alert-rollups; Suricata) usa um segredo dedicado em
x-etershield-key+x-tenant-id. O webhook de incidentes do Wazuh (secção 1) usa a API Key do tenant. - Jira (webhook de entrada) usa
x-api-key+x-tenant-id, com assinatura HMAC opcional. - GoPhish usa assinatura HMAC (secção 10).
- SCIM usa um token Bearer com o scope
/api/scim/v2, e só esse token (secção 11).
O detalhe de cada rota e de cada cabeçalho está no API Reference.