# Authentication, keys & security

> Authenticate every request with an X-API-Key header. Key lifecycle, what a key controls, tenant isolation, encryption, audit logging and BAA availability.

- **HTML:** https://offendersearch.app/docs/authentication
- **Base URL:** https://api.offendersearch.app
- **Authentication:** `X-API-Key` request header
- **OpenAPI:** https://offendersearch.app/openapi.json · https://offendersearch.app/openapi.yaml
- **All documentation as markdown:** https://offendersearch.app/docs.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.

```bash
curl https://api.offendersearch.app/v1/sources \
  -H "X-API-Key: os_live_9f2a…"
```

A missing or unrecognised key returns `401`. An account without billing enabled returns `402`. Both use the standard error envelope with a stable `error.code`.

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

## 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. 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.

## Security

- **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 Business Associate Agreement (BAA) is available to eligible enterprise accounts that process PHI through the API, and a formal SOC 2 examination is underway.

Results are public-record data and are not a consumer report; do not use them for FCRA-covered decisions without appropriate process.

---

## Related

- Previous: [Quickstart](https://offendersearch.app/docs/quickstart.md)
- Next: [Errors, status codes & rate limits](https://offendersearch.app/docs/errors.md)
- Index: [Offendersearch API documentation](https://offendersearch.app/docs.md)