Authentication

API keys

All requests to the tracts.ai API require an API key. Keys are scoped to your account and carry their own rate limits. There are no shared or public keys.

Create a key

Go to Dashboard → API Keys (/dashboard/keys) and click Create key. Give it a descriptive label (e.g. production-ingest or local-dev) so you can identify it later.

Use your key

Send the key in the x-api-key request header:

curl https://api.tracts.ai/counties \
  -H 'x-api-key: YOUR_API_KEY'

Alternatively, the Authorization: Bearer header is also accepted:

curl https://api.tracts.ai/counties \
  -H 'Authorization: Bearer YOUR_API_KEY'

Both headers carry equal weight. If both are present, x-api-key takes precedence.

Security

• Keys are shown once at creation time. Store them in a secret manager or environment variable — never in source code.
• Treat keys like passwords. Anyone who holds a key can make requests billed to your account.
• Use one key per environment (production, staging, local) so you can revoke selectively without disrupting other environments.

Rotating a key

1. Create a new key in the dashboard.
2. Update your environment to use the new key.
3. Revoke the old key once traffic has migrated.

Revoked keys are rejected immediately with a 403 Forbidden response.

Error responses

{
  "error": {
    "code": "missing_key",
    "message": "API key required. Pass x-api-key header or Authorization: Bearer <key>."
  }
}