Authentication and Error Model

Access authentication

Common mints short-lived ES256 access JWTs.

SynckHub verifies JWTs via JWKS and must operate with cached keys when Common is unavailable.

Service authentication

Infra-to-control-plane calls use opaque infra bearer tokens minted by Common.

Do not reuse user JWT assumptions for infra service identity.

Repo integrations use a separate credential class. A repository administrator creates a long-lived repo API token, and the integration exchanges it at POST /v1/api-tokens/exchange for a short-lived access JWT. The opaque token is accepted only by Common; send only the exchanged JWT to SynckHub repository endpoints. See repository-integration-api.md for the complete flow.

Refresh/session model

Common refresh tokens are cookie-based and origin-constrained.

Client behavior must follow Common cookie and allowed-origin rules, especially across multiple origins.

Error envelope

Common and platform contracts use stable error shape:

{ "code": "SOME_CODE", "message": "human-readable message" }

Treat code as the machine contract and message as operator context.