Skip to content

ADR 0003: Security Model

Status

Accepted. Client Credentials authentication with HS256 JWTs is implemented for the first integration release.

Decision

First-version authentication uses:

  • OAuth-style Client Credentials token issuance
  • A single environment-configured integration client
  • HTTP Basic credentials on POST /api/v1/auth/token
  • Short-lived HS256 JWT access tokens (default 60 minutes)
  • Bearer middleware on protected inbound routes when AUTH_ENABLED=true

Refresh tokens, scopes, MongoDB-backed client registries, and customer mapping profiles are intentionally out of scope for this stage.

Transport security prefers TLS. Controlled HTTP is allowed only for trusted local networks.

company_id and organization_id mapping from authenticated client definitions remains a later persistence-stage concern.

Consequences

  • Security controls remain fail-closed when authentication is enabled
  • Secrets stay outside source control and outside logs
  • Auth packages reuse the existing response envelope and error model
  • Local development can keep AUTH_ENABLED=false