Authentication, keys & security

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

Base URL https://api.offendersearch.appThis page as Markdown/docs/authentication.md

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/sources \
  -H "X-API-Key: os_live_9f2a…"

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid X-API-Key header."
  }
}

A missing or unrecognised key returns 401 with that envelope. An account without billing enabled returns 402. Both carry a stable error.code you can switch on — see Errors & status codes.

What a key controls

A key is a pure authentication credential — nothing billable is provisioned on it. Data freshness is chosen per request with the optional freshness parameter (daily by default, or weekly), and 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. Keys are per account, and usage is attributed per key, which is the practical reason to issue one key per environment or per service rather than sharing a single credential across a fleet.

Administrative operations use a separate X-Admin-Key internal credential and are not part of the public API documented here.

Security & HIPAA

Offendersearch is built for compliance-sensitive customers. All API traffic is served over TLS and data is encrypted at rest; API keys are per-account and stored only as one-way hashes; access to production data is least-privilege; and every request is logged for audit. A Business Associate Agreement (BAA) is available to eligible enterprise accounts that process PHI through the API.

Encryption. TLS in transit, AES-256 at rest for stored records and reports.
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.
Audit logging. Requests are logged with account, timestamp, and endpoint; usage is visible to account owners.
Attestations. A BAA is available to eligible enterprise accounts, and a formal SOC 2 examination is underway.

Full details, the BAA request flow, and our data-handling model are on the HIPAA & Security page. Results are public-record data and are not a consumer report; do not use them for FCRA-covered decisions without appropriate process.