Skip to main content
Bearer authentication is the default contract for health-api.

​
Which auth flow to use

Use caseEndpointNotes
Backend or BFF integrationPOST /v1/projects/{project_id}/auth/serverSimplest server-side flow. Uses HTTP Basic auth with a confidential client.
Mobile or web SDK token exchangePOST /v1/projects/{project_id}/auth/sdkExchanges an upstream OIDC token or refresh token.
Raw OAuth integrationPOST /oauth/tokenCanonical OAuth token authority. Form-encoded rather than JSON.
curl -sS -X POST "$BASE_URL/v1/projects/$PROJECT_ID/auth/server" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"scope":"users:read daily_records:read ai_summaries:read"}'
Use the returned access token on protected routes: 
curl -sS "$BASE_URL/users?limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

​
Token claims

ONVY access tokens include these core claims:
  • iss
  • aud
  • exp
  • iat
  • nbf
  • jti
  • project_id
  • sub
  • principal_type
  • scope
If principal_type=user, the token must also include user_id.

​
Scope format

Scopes follow this pattern: 
<resource>[:namespace]:<action>
Examples:
  • users:read
  • daily_records:create
  • chat_completions:create
  • admin.oauth_clients:revoke

​
Convenience endpoints vs canonical OAuth

The JSON convenience endpoints exist to shorten common integration paths:
  • /auth/server wraps client_credentials
  • /auth/sdk wraps token exchange and refresh flows
/oauth/token remains the canonical token endpoint when you need raw grant-level control or direct OAuth interoperability.
Do not build new integrations on X-API-Key. The internal API-key shim remains only for migration-safe compatibility.