Authentication#

Every request to a versioned route (/api/v1/...) carries a Bearer credential and accepts an optional API version header. The /health probes are unauthenticated.

There are two ways to authenticate, both sent as Authorization: Bearer <...>:

Method	How	Scope
Service API key	`Authorization: Bearer <service-api-key>` (`API_KEY`, or optional `API_KEY_2`), validated at the edge.	Not organization-scoped.
User token	`Authorization: Bearer <user-token>` plus `?organization_id=<id>`. The token + org are validated against the TeamBoost platform API; the request proceeds only if the user belongs to that organization.	Scoped to the given organization.

The Bearer credential is matched against the configured service keys first; if it is not a service key, it is treated as a user token, which requires organization_id.

Header / param	Value	Notes
`Authorization`	`Bearer <service-api-key>` or `Bearer <user-token>`	Required.
`organization_id` (query)	Organization id, e.g. `590789`	Required for user tokens; ignored for service keys.
`X-Api-Version`	CalVer `YYYY.M.MICRO`, e.g. `2026.6.2`	Optional — omit to use the latest supported version.

# Service API key
curl https://<host>/api/v1/providers \
  -H "Authorization: Bearer <service-api-key>"

# User token scoped to an organization
curl "https://<host>/api/v1/providers?organization_id=590789" \
  -H "Authorization: Bearer <user-token>"

Authentication outcomes#

Situation	Response
Valid service key	`200`, request proceeds
Valid user token, member of the organization	`200`, request proceeds (org-scoped)
User token without `organization_id`	`400 missing_parameter`
Non-integer `organization_id`	`422 validation_error`
Invalid / unrecognized credential	`401 invalid_api_key`
Valid user token, not a member of the organization	`403 insufficient_permissions`
TeamBoost platform API unreachable	`503 service_unavailable`

Version header behavior#

When X-Api-Version is omitted, the service uses the latest supported version. Send an explicit version to pin client behavior across releases. A version below the minimum or above the latest is rejected with 400 invalid_api_version.

On a successful authenticated request the response echoes the supported range:

X-Api-Latest-Version — newest version the service supports
X-Api-Minimum-Version — oldest version still accepted

Auth roadmap

Per-provider credential storage (provider API keys, OAuth tokens, webhook secrets) is planned but not yet implemented — see the Roadmap.