Skip to main content
Defendis API uses bearer API keys for authentication and enterprise scope for authorization.

​
API key

Send your API key in the Authorization header for all customer endpoints under /api/v1/*: 
Authorization: Bearer <api_key>

#Example request:
curl -sS \
  -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \
  "https://api.defendis.ai/api/v1/watchlists"

​
API key lifecycle

API keys are created and managed in Defendis web app.

Use separate keys

Use unique keys per integration (SIEM, data lake ingestion, SOAR automation).

Rotate regularly

Rotate keys on a schedule (every 60 to 90 days) and immediately after any suspected exposure.

Revoke quickly

Revoke unused keys promptly to reduce your exposure.

​
Authorisation scope

Each API key is bound to a workspace scope. The API enforces access to workspace-owned resources and input validation for scoped endpoints. Out-of-scope requests will return 403 Forbidden Dataleaks endpoints are intentionally strict to prevent data leakage:
  • Requests require scoped inputs (domain, email, or bin depending on endpoint).
  • Missing required scoped parameters return 400 Bad Request.
  • Out-of-scope inputs return 403 Forbidden..
  • Enterprise billing access restrictions may also return 403 Forbidden on protected routes.

​
Common failures

# Missing API key
HTTP/1.1 401 Unauthorized
{ "error": "Missing API key" }

# Invalid or revoked API key
HTTP/1.1 401 Unauthorized
{ "error": "Invalid or revoked API key" }

​
Securing your integration

These recommendations cover the minimum security and observability controls we expect for production integrations, including secrets handling, least-privilege access, and request correlation:

Use a secret manager

Store API keys in a secret manager, never in source control or client-side code.

Apply least privilege

Restrict key access to only the workloads that need it.

Protect auth logs

Never log the full Authorization header.

Capture response request IDs

Capture x-request-id response header to speed up investigations.