Integrations/Fundamentals
Common authentication
Integration endpoints under /api/v1/* accept the tenant API Key in one of two equivalent headers:
x-api-key: <tenant-api-key>
Authorization: Bearer <tenant-api-key>
There are two types of key, both under Settings → Integrations:
| Type | Scope | Validity |
|---|---|---|
| Tenant API Key (single) | Full access to the /api/v1/* routes |
Has an expiry date; old keys with no date are rejected and must be regenerated |
| Per-integration API key (named) | One per server or integration; optionally limited to routes (scopes) | 365 days; individually revocable, with immediate effect; maximum of 20 active per tenant |
Best practices:
- One named key per integration, with the minimum scope. A scope is a route prefix:
/api/v1/monitoring/backup-reportonly opens that route (and the ones beneath it);/api/v1/assetsdoes not open/api/v1/assets-export. Without scopes the key has full access, like the single API Key. Outside the scope the response is401. - The key is shown only once, at creation (EterShield stores only the hash). If it is lost, revoke it and create another.
- An expired or revoked key, or a key from an inactive tenant, is rejected with
401. - Store the key in the secrets vault of the system that uses it, never in versioned files.
Exceptions to the rule above:
- SIEM/IDS ingestion (Wazuh findings, agents and alert-rollups; Suricata) uses a dedicated secret in
x-etershield-key+x-tenant-id. The Wazuh incidents webhook (section 1) uses the tenant API Key. - Jira (inbound webhook) uses
x-api-key+x-tenant-id, with optional HMAC signature. - GoPhish uses HMAC signature (section 10).
- SCIM uses a Bearer token with the
/api/scim/v2scope, and only that token (section 11).
The details of each route and each header are in the API Reference.