Authentication — bearer tokens, anonymous access and multi-key isolation for the DomainScan API.

One header, one format. No query-string fallback (so keys don't end up in access logs).

Authorization: Bearer ds_live_xxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix `ds_live_` Distinguishes live keys. Test keys (sandbox) carry the `ds_test_` prefix.
• No query-string fallback We deliberately do not accept the key as a query parameter. That would risk leaking the key into HTTP server access logs, browser history and referrer headers.
• Case-sensitive The literal `Bearer` prefix must be present. The key payload is case-sensitive.

Most endpoints accept unauthenticated requests. Useful for evaluation, in-browser experiments and quick CLI checks. Limits:

• Rate cap 20 requests per minute per IP, 200 requests per day per IP, 1 burst per second.
• No analytics Anonymous traffic isn't attributed to any account — no per-key dashboard, no usage history.
• Same data Anonymous and authenticated traffic see the same responses; only the rate limits differ.
• Anti-abuse Bot-like User-Agent strings may be rate-limited harder. Set a descriptive UA for production scripts.

Pro plan ships with 3 keys, Business with 10. Use one key per environment or per service — never share a single key across many call sites.

• One key per environment production / staging / development keys can be revoked independently and have separate usage analytics.
• One key per service When multiple services call the API, separate keys make per-service quota and abuse tracking trivial.
• Naming convention Label keys in the dashboard with their service / environment / owner. Speeds incident response.
• Quota is account-wide All keys on an account share the same monthly credit pool — but per-key rate-limit attribution still applies.

Zero-downtime rotation in three steps:

• 1. Generate Create a new key in the dashboard. Both old and new keys are active simultaneously.
• 2. Deploy Push the new key to your secret manager and restart services. Verify traffic is hitting the new key from the dashboard.
• 3. Revoke Revoke the old key. In-flight requests on the old key 401 within seconds. New traffic continues on the new key uninterrupted.

Revoke immediately. Audit retroactively.

• Revoke first Use the dashboard 'Revoke' button. Takes effect globally within seconds. No grace period.
• Audit usage Inspect the key's request log for anomalous endpoints, IPs or volumes since the suspected compromise window.
• Issue a fresh key Generate a replacement. Update the leaked-credential location (env var, secret manager, .env file) and restart consumers.
• Notify if material If the leak involved customer data or downstream impact, follow your organization's incident-response process. Email [email protected] if you need a usage-audit export.

Treat the key like a password. The two cardinal sins:

• Don't commit to git Even in a private repo. Once a key hits git history, assume it's compromised — secret-scanners look for the `ds_live_` prefix.
• Don't ship in frontend Never embed in a public-facing webapp, mobile app or browser extension. Proxy through your backend with appropriate scopes.
• Use a secret manager AWS Secrets Manager, GCP Secret Manager, Vault, Doppler, 1Password Secrets Automation. CI/CD: GitHub Actions / GitLab CI secret variables.
• Per-environment env vars Inject at runtime via env vars. Production secret manager refreshes the env var on rotation; the app restarts cleanly.