Authentication

Every request to Synthient is authenticated with a single API key, which carries a set of scopes that determine which endpoints and feeds you can access.

Getting a key

API keys are issued from the Synthient dashboard. If you don't have one yet, contact us and we'll provision one with the scopes you need. Keys never expire, but can be rotated or revoked from the dashboard at any time.

Sending the key

TransportWhere to put the key
HTTPx-api-key: <YOUR_API_KEY> request header
gRPCx-api-key request metadata
CLISYNTHIENT_API_KEY env var, then a .env file in the working directory, then the OS keychain entry saved by synthient auth

API keys are UUIDs, for example b28fc277-5893-4025-8fc4-f61aa161d462. That example is not a real key.

Authenticated request

curl -G https://api.synthient.com/api/v4/lookup/ip/8.8.8.8 \
  -H "x-api-key: $SYNTHIENT_API_KEY"

A missing, malformed, or unknown key returns 401 Unauthorized.

All Synthient APIs are server-to-server.

Scopes

Each API key is granted a set of scopes that control which surfaces it can call. BASIC covers the synchronous IP APIs; every feed exposes a separate *_FEED scope (parquet exports) and *_STREAM scope (real-time NDJSON stream).

ScopeGrants
BASICIP lookups (GET /lookup/ip/{ip_address}, POST /lookup/ips) and GET /account/me.
PROXY_FEEDSproxies parquet exports.
PROXY_FIREHOSEproxies real-time NDJSON stream.
ANONYMIZERS_FEED / ANONYMIZERS_STREAMAnonymizer (VPN/Tor/private-relay) exports / stream.
TORRENTS_FEED / TORRENTS_STREAMBitTorrent peer-observation exports / stream.
HONEYPOT_HTTP_FEED / HONEYPOT_HTTP_STREAMHTTP honeypot exports / stream.
HONEYPOT_HTTPS_FEED / HONEYPOT_HTTPS_STREAMTLS honeypot (ClientHello) exports / stream.
HONEYPOT_DNS_FEED / HONEYPOT_DNS_STREAMHelios tunnel destination exports / stream.
HONEYPOT_ADB_FEED / HONEYPOT_ADB_STREAMAndroid Debug Bridge honeypot exports / stream.
GEOLOCATION_FEEDGeolocation dataset exports (Parquet, gzip CSV, and MMDB).
WHOIS_FEEDWHOIS dataset exports.
NETWORK_IOCS_FEED / NETWORK_IOCS_STREAM, FILE_IOCS_FEED / FILE_IOCS_STREAM, WHOIS_STREAMReserved for upcoming feeds. No endpoint accepts them yet.

Inspect the scopes granted to your current key by calling GET /account/me:

{
  "scopes": ["BASIC", "PROXY_FEEDS", "PROXY_FIREHOSE", "ANONYMIZERS_STREAM"],
  "lookup_quota": { "credits": 982341, "resets_in": 1893456 }
}

A request to an endpoint your key isn't scoped for returns 403 Forbidden.

Next steps

  • Errors: what 401, 402, and 403 responses look like and how to recover.
  • Rate Limits: quota, concurrent stream limits, and backoff guidance.
  • Account API: programmatically inspect scopes and remaining quota.