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
Section titled “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
Section titled “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
Section titled “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
Section titled “Per-product detail”- Iris API authentication — open key, header, and HMAC examples; applies to Iris Investigate, Enrich, and Detect
- DNSDB API authentication —
X-API-Keyheader setup, Punycode encoding requirements - Lookups and Monitors authentication — shares credentials and methods with the Iris API
- Threat Feeds quick start — header and HMAC examples for Feed and Download APIs
- SIE user guide — Batch, Remote Access, and Direct Connect
- MCP Server authentication —
X-Api-Keyheader against the hosted MCP endpoint
Rate limits
Section titled “Rate limits”Each product enforces its own rate limits and quotas by account tier:
- Iris rate limits and the account information endpoint for Iris usage
- Threat Feeds rate limits — 2 queries/minute, 120 queries/hour
- MCP Server rate limits — 10 requests/second with a burst of 20
- DNSDB quotas are time- or block-based and tied to your key; see the DNSDB user guide
SDK and tooling
Section titled “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_USERNAMEandDOMAINTOOLS_API_KEYenvironment variables or pass-u/-kflags 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_KEYand pass it to your client as anX-Api-Keyheader. The server supplies the username server-side.
See the full setup guides:
Single Sign-On
Section titled “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.