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	Stored in your OS keychain by `synthient auth`, or read from `SYNTHIENT_API_KEY` env var

API keys are UUIDs for example c23f3dab-5c04-4416-af21-c6b879bb90b9. Don't paste the example; pull your own key from the dashboard and inject it via an environment variable as the code samples below do.

Authenticated request

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

Scopes

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

Scope	Grants
`BASIC`	IP and domain lookups (`GET /lookup/ip/{ip}`, `POST /lookup/ips`, `GET /lookup/domain/{domain}`) 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`	DNS honeypot exports / stream.
`HONEYPOT_ADB_FEED` / `HONEYPOT_ADB_STREAM`	Android Debug Bridge honeypot exports / stream.

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.

Security best practices

Never commit keys. Read the key from an environment variable or a secret manager (1Password, AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault). The conventional env-var name is SYNTHIENT_API_KEY.
Use one key per environment. Issue separate keys for development, staging, and production so you can rotate or revoke without coordinating across teams.
Don't expose keys to browsers. All Synthient APIs are server-to-server. If you need client-side enrichment, proxy the request through your backend.
Rotate on suspicion. Revoke and reissue immediately if a key may have been logged, shared, or pushed to a public repo. Inflight requests with the old key fail with 401.
Scope keys narrowly. A key that only needs PROXY_FIREHOSE shouldn't carry BASIC or other feed scopes. Reach out to support if you need additional scopes.

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.