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

# Authentication

> Create an API key and authenticate requests to the Infrawatch API

The Infrawatch API uses API keys to authenticate requests. You can create and
manage keys in [API access](https://app.infrawatch.com/accounts/api-access).

Send the key in the `X-API-Key` request header:

```bash theme={null}
curl --get "https://api.infrawatch.com/api/v1/search/hosts" \
  --header "X-API-Key: ${INFRAWATCH_API_KEY}" \
  --data-urlencode "q=ip:1.1.1.1" \
  --data "limit=1"
```

You must make every API call over HTTPS. Requests made over plain HTTP, without
an API key, or without the required scope will fail.

## Create a key

1. Open [API access](https://app.infrawatch.com/accounts/api-access).
2. Choose the account that should own the key.
3. Select only the scopes the integration needs.
4. Create the key and copy the secret when it is shown.

<Warning>
  Treat the secret like a password. Store it in server-side secret storage and
  never commit it, log it, or expose it in browser code.
</Warning>

## Set the header

Store the key in an environment variable:

```bash theme={null}
export INFRAWATCH_API_KEY="<your-api-key>"
```

Then send it with each request:

```text theme={null}
X-API-Key: <your-api-key>
```

Authentication, account selection, scopes, and usage limits are derived from
the key. Do not send an organisation identifier with public API requests.

## Choose scopes

Scopes limit what a key can do. Common search scopes include:

| Scope              | Access                                             |
| ------------------ | -------------------------------------------------- |
| `search.view`      | Search, query validation, schemas, and bulk lookup |
| `search.aggregate` | Exact counts and aggregations                      |
| `reports.view`     | Search reports and retrieve report indicators      |

An endpoint page lists the scope it requires. A key can only use scopes allowed
by its owning account.

## Handle authentication errors

| Status | Meaning                                                      |
| ------ | ------------------------------------------------------------ |
| `401`  | The API key is missing, invalid, expired, or revoked         |
| `403`  | The key is valid but lacks the required scope or entitlement |
| `429`  | The request exceeded an applicable usage or rate limit       |

API errors include a stable `error.code` and `request_id`. Keep the request ID
when contacting support.