# ADR-005: Bearer Token Authentication

## Status

Accepted

## Context

The API must authenticate requests using API keys. Each CRM tenant has one
or more named keys for rotation support. The question is which HTTP header
convention to use.

## Decision

Use `Authorization: Bearer <key>` (RFC 6750).

## Options Considered

### Option A: X-API-Key custom header (rejected)

- **Pro**: Used by many API providers (Stripe, SendGrid). Visually distinct
  from OAuth bearer tokens, which may reduce confusion in environments that
  also use OAuth.
- **Con**: Non-standard. Many API gateways, load balancers, and HTTP client
  libraries have first-class support for `Authorization: Bearer` but require
  custom configuration for `X-API-Key`. CRM developers familiar with OAuth2
  workflows will expect `Authorization: Bearer` and may lose time debugging
  when their default HTTP client configuration sends the wrong header.

### Option B: Authorization: Bearer (chosen)

- **Pro**: RFC 6750 standard. Universal tooling support. CRM developers can
  use their existing HTTP client configuration without modification. Azure
  API Management, AWS API Gateway, and Kong all support Bearer tokens natively.
- **Con**: May be confused with OAuth2 bearer tokens. A CRM developer might
  assume token exchange or refresh is supported.
- **Mitigation**: The API documentation and 401 error message explicitly
  state that the token is a static API key, not an OAuth token. No token
  exchange endpoint exists.

### Option C: Basic auth (not considered)

Would require Base64 encoding and a username:password pair. Unnecessary
complexity for a static API key.

## Consequences

- The `authenticate_request` dependency reads the `Authorization` header
  and extracts the token after the `Bearer ` prefix.
- FastAPI's `HTTPBearer` security scheme is used, which auto-generates the
  correct OpenAPI security definition.
- 401 responses include the message:
  `"A valid API key is required. Provide it as: Authorization: Bearer <key>"`
- Key validation uses `secrets.compare_digest` for constant-time comparison.

## Participants

- UX advocate (proposed Bearer as RFC standard)
- Architect (originally proposed X-API-Key, accepted Bearer)