EterShieldDocs
etershield.com
PTLog in
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-report only opens that route (and the ones beneath it); /api/v1/assets does not open /api/v1/assets-export. Without scopes the key has full access, like the single API Key. Outside the scope the response is 401.
  • 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/v2 scope, and only that token (section 11).

The details of each route and each header are in the API Reference.

EterShield, an Eter Growth platform