Authentication
Most integration endpoints use one of these two headers (equivalent: they resolve to the same key, validated by the same SHA-256 hash):
x-api-key: <api_key>
Authorization: Bearer <api_key>
x-api-key is the historical header and the one used in the examples below; Bearer exists for generic REST integrators. It applies to all /api/v1/* routes that use resolveApiKey().
Key types
| Type | How to obtain | Scope | Expiry / revocation |
|---|---|---|---|
| Single tenant key | Settings → Integrations → API Key | Full access to /api/v1/* routes |
Expires (apiKeyExpiresAt); old keys without an expiry date are rejected and must be regenerated. Rotation = new key. |
| Named key | Settings → Integrations → "API keys per integration" (ADMIN/SUPER_ADMIN only) | List of scopes; empty list = full access, like the single key | Valid for 365 days; individually revocable (stops working immediately); maximum of 20 active keys per tenant |
Common to both:
- The key is never stored in clear text: only the SHA-256 hash is kept in the database. The named key has the format
etsh_…and is shown only once, on creation; it cannot be recovered afterwards. - A key is rejected (
401) if it is unknown, expired, revoked, or if the tenant is notACTIVE. - Each successful use updates the last-used timestamp asynchronously (
lastUsedAton the named key,apiKeyLastUsedAton the single key). - Key creation and revocation are recorded in the audit log.
- A request authenticated by API key is treated as the tenant's
ADMINrole, with no active entity (tenant-wide context).
Named key scopes
A scope is a route prefix (/api/v1/monitoring/backup-report). The key is only accepted on routes that are equal to the prefix or below it (<prefix>/…), never by a simple string prefix match: the scope /api/v1/assets does not open /api/v1/assets-export. Outside the scope the response is 401. Validation rules: path starting with /api/, only A-Z a-z 0-9 / _ -, no // or .., at most 20 scopes per key.
Example: a key for the backup script, limited to a single route:
curl -X POST https://www.etershield.com/api/v1/monitoring/backup-report \
-H "Authorization: Bearer <chave_nomeada>" \
-H "Content-Type: application/json" \
-d '{ ... }'
The SCIM token is a named key with the scope /api/scim/v2. See SCIM 2.0 below.
MCP connector (Claude). A named key with the scope /mcp (the "MCP connector (Claude)" option on the named keys card) authenticates the EterShield MCP connector. The key is stored only as a hash, so it is not sent in the URL. No scopes = full access; the /mcp scope works; a scope such as /api/v1/assets does not. Revoked or expired keys, and keys of inactive organisations, are rejected.
Other authentication schemes
- Browser session: some endpoints are used only by the interface and do not accept an API key; this is noted in each case.
- API key or session: they accept both, for example
/issues,/admin/data-export,/evidence,/capa,/audit-plans. - SIEM/IDS ingestion (Wazuh findings, agents and alert-rollups; Suricata): dedicated secret in the
x-etershield-keyheader +x-tenant-id, notx-api-key.POST /integrations/wazuh/incidents, by contrast, uses the tenant API key. - SCIM: Bearer token with the scope
/api/scim/v2(see SCIM 2.0).