Autenticação
A generalidade dos endpoints de integração usa um destes dois cabeçalhos (equivalentes, resolvem para a mesma chave, validada pelo mesmo hash SHA-256):
x-api-key: <api_key>
Authorization: Bearer <api_key>
x-api-key é o cabeçalho histórico e o usado nos exemplos abaixo; Bearer existe para integradores REST genéricos. Aplica-se a todas as rotas /api/v1/* que usam resolveApiKey().
Tipos de chave
| Tipo | Como se obtém | Âmbito | Expiração / revogação |
|---|---|---|---|
| Chave única do tenant | Definições → Integrações → API Key | Acesso total às rotas /api/v1/* |
Expira (apiKeyExpiresAt); chaves antigas sem data de expiração são rejeitadas e têm de ser regeneradas. Rotação = nova chave. |
| Chave nomeada | Definições → Integrações → «Chaves API por integração» (só ADMIN/SUPER_ADMIN) | Lista de scopes; lista vazia = acesso total, como a chave única | Validade de 365 dias; revogável individualmente (deixa de funcionar de imediato); máximo de 20 chaves ativas por tenant |
Pontos comuns a ambas:
- A chave nunca é guardada em claro: só o hash SHA-256 fica na base de dados. A chave nomeada tem o formato
etsh_…e é mostrada uma única vez, na criação; não pode ser recuperada depois. - Uma chave é rejeitada (
401) se for desconhecida, expirada, revogada, ou se o tenant não estiverACTIVE. - Cada utilização bem-sucedida atualiza a data de última utilização de forma assíncrona (
lastUsedAtna chave nomeada,apiKeyLastUsedAtna chave única). - A criação e a revogação de chaves ficam no audit log.
- Um pedido autenticado por chave de API é tratado como papel
ADMINdo tenant, sem entidade ativa (contexto tenant-wide).
Scopes das chaves nomeadas
Um scope é um prefixo de rota (/api/v1/monitoring/backup-report). A chave só é aceite em rotas iguais ao prefixo ou abaixo dele (<prefixo>/…), nunca por simples início de texto: o scope /api/v1/assets não abre /api/v1/assets-export. Fora do scope a resposta é 401. Regras de validação: caminho a começar por /api/, só A-Z a-z 0-9 / _ -, sem // nem .., no máximo 20 scopes por chave.
Exemplo, chave para o script de backups, limitada a uma rota:
curl -X POST https://www.etershield.com/api/v1/monitoring/backup-report \
-H "Authorization: Bearer <chave_nomeada>" \
-H "Content-Type: application/json" \
-d '{ ... }'
O token SCIM é uma chave nomeada com o scope /api/scim/v2, ver SCIM 2.0 abaixo.
Conector MCP (Claude). Uma chave nomeada com o âmbito /mcp (opção «Conector MCP (Claude)» no cartão de chaves nomeadas) autentica o conector MCP do EterShield. A chave é guardada apenas em forma de hash, por isso não vai no URL. Sem âmbitos = acesso total; o âmbito /mcp serve; um âmbito como /api/v1/assets não serve. Chaves revogadas, expiradas ou de organizações inativas são rejeitadas.
Outros esquemas de autenticação
- Sessão de browser: alguns endpoints são usados apenas pela interface e não aceitam chave de API; está assinalado em cada caso.
- Chave de API ou sessão, aceitam ambos, por exemplo
/issues,/admin/data-export,/evidence,/capa,/audit-plans. - Ingestão de SIEM/IDS (Wazuh findings, agents e alert-rollups; Suricata), segredo dedicado no header
x-etershield-key+x-tenant-id, nãox-api-key.POST /integrations/wazuh/incidents, pelo contrário, usa a chave de API do tenant. - SCIM, token Bearer com scope
/api/scim/v2(ver SCIM 2.0).