> ## Documentation Index
> Fetch the complete documentation index at: https://docs.defendis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

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/*`:

```http theme={null}
Authorization: Bearer <api_key>
```

```bash theme={null}
#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](https://app.defendis.ai).

<CardGroup cols={1}>
  <Card title="Use separate keys">
    Use unique keys per integration (SIEM, data lake ingestion, SOAR automation).
  </Card>

  <Card title="Rotate regularly">
    Rotate keys on a schedule (every 60 to 90 days) and immediately after any suspected exposure.
  </Card>

  <Card title="Revoke quickly">
    Revoke unused keys promptly to reduce your exposure.
  </Card>
</CardGroup>

## 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 <span style={{ color: "#dc2626", fontWeight: 500 }}>403 Forbidden</span>

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 <span style={{ color: "#dc2626", fontWeight: 500 }}>400 Bad Request</span>.
* Out-of-scope inputs return <span style={{ color: "#dc2626", fontWeight: 500 }}>403 Forbidden</span>..
* Enterprise billing access restrictions may also return <span style={{ color: "#dc2626", fontWeight: 500 }}>403 Forbidden</span> on protected routes.

## Common failures

```http theme={null}
# Missing API key
HTTP/1.1 401 Unauthorized
{ "error": "Missing API key" }
```

```http theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Use a secret manager">
    Store API keys in a secret manager, never in source control or client-side code.
  </Card>

  <Card title="Apply least privilege">
    Restrict key access to only the workloads that need it.
  </Card>

  <Card title="Protect auth logs">
    Never log the full Authorization header.
  </Card>

  <Card title="Capture response request IDs">
    Capture `x-request-id` response header to speed up investigations.
  </Card>
</CardGroup>