Skip to content

Authentication

All DomainTools APIs require authentication with an API key tied to your account. This page summarizes the authentication schemes across products and links to per-product detail.

API credentials

Where you get the key depends on the product:

  • Iris, Lookups and Monitors, Threat Feeds — the group's API administrator manages keys at https://research.domaintools.com under Account → API Admin. Only the API owner can reset the key.
  • MCP Server — find and rotate your key at your account dashboard.
  • Farsight DNSDB, Farsight SIE — keys are provisioned by DomainTools Enterprise Support at enterprisesupport@domaintools.com. Contact support to reset.

For guidance on storing and rotating credentials, see Storing credentials securely.

Quick start

If your account has access to the Iris, Lookups and Monitors, or Threat Feeds APIs, this curl hits the account endpoint and confirms your credentials work:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.domaintools.com/v1/account"

A 200 response returns your account summary and provisioned products. A 403 response means the credentials are missing, invalid, or not provisioned for the endpoint — the response body distinguishes the cases.

For DNSDB, use the api.dnsdb.info host instead:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/rate_limit"

Authentication schemes

Product Host Header Query-string HMAC
Iris Investigate / Enrich / Detect APIs api.domaintools.com Yes Yes (not recommended) Yes
Lookups and Monitors APIs api.domaintools.com Yes Yes (not recommended) Yes (shared with Iris)
Threat Feeds api.domaintools.com Yes Yes (not recommended) Yes
Farsight DNSDB API api.dnsdb.info X-API-Key header No No
Farsight SIE Batch batch.sie-remote.net apikey in JSON body (UUID) No No

Pick a method based on where you're calling from:

  • HMAC — recommended for production. Each request is signed with a short-lived timestamp, so a captured signature can't be replayed after it expires. The API key never travels over the wire.
  • Header (X-Api-Key) — good default for SDKs, CI jobs, and scripts. The key travels in every request, but it stays out of URLs and server access logs.
  • Query-string — not recommended. Credentials appear in access logs, browser history, proxy caches, and CDN logs. Use only for one-off testing, never in production.

Farsight SIE Batch is the exception — it accepts credentials only as an apikey field inside the JSON POST body, in UUID format. See the SIE Batch API reference. The Python SDK uses header authentication for Threat Feed streaming endpoints even though the API itself accepts HMAC.

SIE also offers Remote Access (AXAMD and SRA over TLS certificates) and Direct Connect (SSH key plus IP allowlist). See the SIE user guide for access modes beyond Batch.

Per-product detail

Rate limits

Each product enforces its own rate limits and quotas by account tier:

SDK and tooling

The Python SDK and MCP Server read credentials from environment variables or a config file — you don't build auth headers by hand. The two tools use different credential formats:

  • Python SDK — requires both API username and API key. Set DOMAINTOOLS_USERNAME and DOMAINTOOLS_API_KEY environment variables or pass -u / -k flags to the CLI. HMAC-SHA256 signing is the default; header auth activates automatically for Real-Time Threat Feed endpoints.
  • MCP Server — requires only an API key. Set DOMAINTOOLS_API_KEY and pass it to your client as an X-Api-Key header. The server supplies the username server-side.

See the full setup guides:

Single Sign-On

Enterprise accounts can enable SAML 2.0 SSO (Microsoft Entra ID, Okta, and other SAML identity providers) for the DomainTools web UI. SSO governs UI access, not API authentication — API requests still use the credentials described above.