# 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](mailto:contact@synthient.com) 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 `b28fc277-5893-4025-8fc4-f61aa161d462`. That example is not a real key; pull your own from the dashboard and inject it via an environment variable as the code samples below do.

**Authenticated request**

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

```bash title="CLI"
synthient auth
```

```python title="Python"
import os, requests

res = requests.get(
    'https://api.synthient.com/api/v4/lookup/ip/8.8.8.8',
    headers={'x-api-key': os.environ['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`](https://docs.synthient.com/account):

```json
{
  "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`](https://docs.synthient.com/errors).

## 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`](https://docs.synthient.com/errors).
- **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](https://docs.synthient.com/errors): what `401`, `402`, and `403` responses look like and how to recover.
- [Rate Limits](https://docs.synthient.com/rate-limits): quota, concurrent stream limits, and backoff guidance.
- [Account API](https://docs.synthient.com/account): programmatically inspect scopes and remaining quota.