Sex Offender Search API · v1.0.0

Authentication, keys & security

The X-API-Key header, key lifecycle and rotation, and the security posture behind the API.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

The X-API-Key header

Authenticate every request with your secret key in the X-API-Key header. Keys are created, named, rotated, and revoked from the API keys page. A key’s secret is shown in full only once, at creation, and is stored only as a one-way hash — keep it in a secret manager, and never in client-side code.

Authorization header
curl https://api.offendersearch.app/v1/records/rec_4b1e \
  -H "X-API-Key: os_live_9f2a…"
401 Unauthorized
{
  "detail": "Missing or invalid API key. Send it in the X-API-Key header."
}

A missing or unrecognised key returns 401 with that body (some endpoints word the sentence slightly differently). An account with no active subscription and no free-trial searches left returns 402. Both carry a detail sentence that says which. GET /v1/sources is the one endpoint that needs no key — see Errors & status codes.

What a key controls

A key is a pure authentication credential — nothing billable is provisioned on it. Every key can run both search modes: the default Regular search and, by sending a live block, a Live re-verification (billed per live source). Verification reports are a separate endpoint (POST /v1/report) that any valid key can call, billed per document. There are no per-key feature scopes to configure, so a key created today can call every endpoint documented here.

Rotation

Issue a second key, deploy it, then revoke the first — both are valid at once, so rotation needs no downtime window. You can also rotate a key in place from the API keys page: it issues a new secret, shown once, and the old secret stops working immediately. Each key records when it was last used, which is the practical reason to issue one key per environment or per service rather than sharing a single credential across a fleet.

Security & HIPAA

OffenderSearch is built for compliance-sensitive customers. All API traffic is served over TLS and stored data is encrypted at rest; API keys belong to one account and are stored only as one-way hashes; and every billable search is recorded against the account that ran it. A Business Associate Agreement (BAA) can be executed by any account from the dashboard.

  • Encryption. TLS in transit, AES-256 at rest for stored searches and their results.
  • Per-key hashing. Secrets are hashed at rest — a database read never exposes a usable key.
  • Access controls & tenant isolation. Data is scoped per account; one customer can never read another’s keys, usage, or reports.
  • Search history. Every billable search is recorded with its account, time and query, and shows in the dashboard’s usage and search history for the 14 days results are kept.
  • Attestations. The BAA is a click-through agreement executed by a signed-in person in the dashboard, never by an API key; the executed copy is available as a PDF.
Full details, how the BAA works, and our data-handling model are on the HIPAA & Security page. Results from the standard endpoints are public-record data and are not a consumer report; do not use them for FCRA-covered decisions. FCRA-regulated use runs as FCRA orders under FCRA Partner Access — see the FCRA API.

Product overview