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
| Transport | Where to put the key |
|---|---|
| HTTP | x-api-key: <YOUR_API_KEY> request header |
| gRPC | x-api-key request metadata |
| CLI | SYNTHIENT_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).
| Scope | Grants |
|---|---|
BASIC | IP lookups (GET /lookup/ip/{ip_address}, POST /lookup/ips) and GET /account/me. |
PROXY_FEEDS | proxies parquet exports. |
PROXY_FIREHOSE | proxies real-time NDJSON stream. |
ANONYMIZERS_FEED / ANONYMIZERS_STREAM | Anonymizer (VPN/Tor/private-relay) exports / stream. |
TORRENTS_FEED / TORRENTS_STREAM | BitTorrent peer-observation exports / stream. |
HONEYPOT_HTTP_FEED / HONEYPOT_HTTP_STREAM | HTTP honeypot exports / stream. |
HONEYPOT_HTTPS_FEED / HONEYPOT_HTTPS_STREAM | TLS honeypot (ClientHello) exports / stream. |
HONEYPOT_DNS_FEED / HONEYPOT_DNS_STREAM | Helios tunnel destination exports / stream. |
HONEYPOT_ADB_FEED / HONEYPOT_ADB_STREAM | Android Debug Bridge honeypot exports / stream. |
GEOLOCATION_FEED | Geolocation dataset exports (Parquet, gzip CSV, and MMDB). |
WHOIS_FEED | WHOIS dataset exports. |
NETWORK_IOCS_FEED / NETWORK_IOCS_STREAM, FILE_IOCS_FEED / FILE_IOCS_STREAM, WHOIS_STREAM | Reserved 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, and403responses look like and how to recover. - Rate Limits: quota, concurrent stream limits, and backoff guidance.
- Account API: programmatically inspect scopes and remaining quota.