Docs / Integrations & API / API access
Browse Integrations & API
Integrations & API

API access

Create and manage API keys for the ScoutDNS Operator API under Settings, API Keys. X-API-ACCESS-KEY header authentication, key lifecycle, OpenAPI reference on SwaggerHub.

Updated Oct 2, 2026 • 3 min read

The ScoutDNS Operator API exposes the same primitives as the console, sites, networks, policies, allow/block lists, and activity, as a REST/JSON service. Admins self-manage the account’s keys under Settings → API Keys.

[!NOTE] This article covers the public Operator API. For access to specialized APIs (e.g. the OEM API), contact support directly.

Create an API key

  1. Open Settings → API Keys and click New API Key.
  2. Enter a description (what the key is for, which system uses it) and Save.
  3. Use the Copy button in the API Key column to grab the key value.

The API Keys section

Every key has two values, and they are not interchangeable:

  • Key ID: a UUID that identifies the key in the list. It cannot authenticate anything.
  • API Key: the credential itself. It is never displayed on screen, but you can copy it at any time with its Copy button, at creation or later.

A key’s detail view with its Copy buttons

Keys have no per-key scopes or expiry; each key carries full Operator API access for the account. The number of keys you can hold is your plan’s API keys allowed allowance, shown under Settings → Subscription.

[!IMPORTANT] Revoking a key is instant and cannot be undone; anything still using it starts failing immediately. To rotate a key, create the new key first, move your integrations over, then revoke the old one. If your plan allows only one key, revoke the old key first, then create the new one, and expect integrations to fail until they have the new key.

Authenticate API requests

Send the key in the X-API-ACCESS-KEY header on every request. The API doesn’t read the Authorization header, and it answers any request without X-API-ACCESS-KEY with a 403.

To check that a key works:

curl -H "X-API-ACCESS-KEY: <YOUR_KEY>" https://api.scoutdns.com/app/whoami

On Windows, type curl.exe rather than curl, because Windows PowerShell maps curl to a different command.

Endpoints use the API’s own names, and sites are called locations. To list your sites:

curl -H "X-API-ACCESS-KEY: <YOUR_KEY>" https://api.scoutdns.com/app/getLocations
import requests

resp = requests.get(
    "https://api.scoutdns.com/app/getLocations",
    headers={"X-API-ACCESS-KEY": API_KEY},
)
resp.raise_for_status()
print(resp.json())

Some endpoints take query parameters. Usage data, for example, takes a date range in YYYY-MM-DD format:

curl -H "X-API-ACCESS-KEY: <YOUR_KEY>" "https://api.scoutdns.com/app/getUsageBillingStats?from=2026-09-01&till=2026-09-30"

If a request gets a 405 saying the function isn’t available for your subscription, contact support and we’ll check it.

API reference

The API reference is on SwaggerHub, and it uses the same X-API-ACCESS-KEY header:

app.swaggerhub.com/apis/ScoutDNS/ScoutDNS

ScoutDNS API documentation on SwaggerHub

Was this article helpful?
Still stuck? Open a ticket and we'll follow up by email.
Open a ticket
Last updated Oct 2, 2026