Authentication & keys
One header, one key format, every product.
The X-API-Key header
Send your secret key in the X-API-Key header on every request. There is no OAuth flow and no bearer token for the APIs; the FCRA consumer portal issues its own short-lived session for consumers, documented on the FCRA consumer portal page.
POST /v1/search HTTP/1.1
Host: api.offendersearch.app
X-API-Key: os_live_************************
Content-Type: application/jsonThe only unauthenticated endpoints are the coverage catalogs — GET /v1/sources and GET /v1/criminal/sources — so you can audit coverage before you integrate.
Key lifecycle
| Action | Where | Notes |
|---|---|---|
| Create | Dashboard → API keys | Name it for its service or environment. The secret is shown in full once, at creation, and stored only as a one-way hash. |
| Test key | Same page, Create test key | Begins os_test_; accepted only by sandbox.offendersearch.app; never billed. |
| Live key | Same page, Create key | Begins os_live_; accepted only by api.offendersearch.app; every billable call is recorded against the account. |
| Rotate | Create the new key, deploy it, then revoke the old one | Two live keys can coexist, so a rotation has no gap. |
| Revoke | Same page | Immediate. Requests with a revoked key answer 401. |
Issue one key per environment or per service rather than sharing one credential across a fleet; a leaked key is then one revocation, not a redeploy of everything.
Organisation credentials
Keys belong to the account (the organisation), not to the person who created them. Team members are managed under Dashboard → Team; a member who leaves does not take the keys with them, and a key keeps working until someone revokes it. Entitlements — the Map API, FCRA partner status — are properties of the account and apply to every key on it.
Authentication errors
| Status | Meaning | Fix |
|---|---|---|
401 | No key, an unknown key, a revoked key, or a test key sent to the live host (and the reverse). The detail sentence varies by route — branch on the status, not the words. | Check the header name (X-API-Key), the prefix against the host, and that the key has not been revoked. |
403 | The key is valid but the account lacks the entitlement: the Map API not turned on, not an approved FCRA partner, or a consumer account on a business endpoint. | The response detail.code names it. Enable it in the dashboard or request access. |
Secure handling
- Keep keys in a secret store or environment variable (
OFFENDERSEARCH_API_KEY), never in client-side code, mobile apps or a repository. - Call the API from your backend. A browser or mobile client that holds a live key has published it.
- All traffic is TLS. Stored data is encrypted at rest; keys are stored only as one-way hashes; every billable search is recorded with its account, time and query and is visible in the dashboard for the 14 days results are kept.
- A Business Associate Agreement can be executed from the dashboard by a signed-in person on the account (Dashboard → BAA).