Getting started
Authentication
Every REST request authenticates with a Bearer API key. Sandbox keys are free and deterministic; live keys run real scrapes and unlock after email verification.
Bearer API keys
Send your key in the Authorization header on every request. Keys are opaque random strings with a human-readable prefix — scout_live_… for production and scout_test_… for the sandbox.
GET /v1/search?location=Split,HR HTTP/1.1
Host: api.scoutingapi.com
Authorization: Bearer scout_live_8sFq2nM4kP9wZ1vR7tYx0aBcDeFgHiJk
Accept: application/jsonA request with no header, a malformed header, or an unknown/revoked key returns 401 authentication_error — never billed. Auth is checked before validation, billing, or any upstream work.
Sandbox vs live keys
| scout_test_… (sandbox) | scout_live_… (live) | |
|---|---|---|
| Backing data | Deterministic fixtures (unified schema) | Real fan-out to live upstream actors |
| Credits | Always 0 (sandbox allotment only) | Charged per the credit tiers |
| Rate limit | Applies (sandbox plan limits) | Applies (the key's plan limits) |
| Envelope & schema | Byte-identical to live | — |
| Email verification | Not required | Required before live credit is usable |
Because the sandbox returns the byte-identical envelope, schema, error shapes and pagination as live, code you build against a test key works unchanged against a live key.
The email-verification gate
scout_test_ keys and the deterministic sandbox still work fully — so you can build and test end-to-end before verifying. This is a free-tier abuse control, not a wall in front of evaluation.Creating, rotating & revoking keys
Manage keys from the dashboard:
- Create & label as many keys as you need, choosing the sandbox or live environment per key.
- Shown once. A new key’s secret is displayed a single time on creation — it is stored only as a SHA-256 hash and is never logged or recoverable. Copy it then.
- Rotate / revoke at any time; a revoked key immediately returns
401 revoked_api_key. - Every key belongs to one account and inherits that account’s plan — which sets the credit balance it draws from and its per-key rate-limit bucket.
One balance, two surfaces