Authentication

The Infrawatch API uses API keys to authenticate requests. You can create and manage keys in API access. Send the key in the X-API-Key request header:

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

Open API access.
Choose the account that should own the key.
Select only the scopes the integration needs.
Create the key and copy the secret when it is shown.

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.

Set the header

Store the key in an environment variable:

export INFRAWATCH_API_KEY="<your-api-key>"

Then send it with each request:

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.

Start here

Search

External Surface Intelligence

Alerting

Remote Browser

Rules

Reports

Projects

Usage

Create a key

Set the header

Choose scopes

Handle authentication errors

​Create a key

​Set the header

​Choose scopes

​Handle authentication errors

Create a key

Set the header

Choose scopes

Handle authentication errors