Skip to content

auth

Purpose

auth is the OAuth 2.0 client-credentials authorisation server for the platform. It issues short-lived JWTs, exposes a JWKS endpoint so downstream services can verify tokens without calling auth on every request, and manages the lifecycle of API clients and their secrets. Every service in the platform validates bearer tokens against auth's public keys via @sa-platform/auth-client.

Key endpoints

POST /v1/auth/oauth/token — issue a JWT via client-credentials grant GET /.well-known/jwks.json — public JWKS endpoint (consumed by all services for token verification) POST /v1/auth/admin/api-clients — register a new API client GET /v1/auth/admin/api-clients — list API clients GET /v1/auth/admin/api-clients/:id — fetch a single client PATCH /v1/auth/admin/api-clients/:id — update client metadata POST /v1/auth/admin/api-clients/:id/secrets — rotate / add a client secret DELETE /v1/auth/admin/api-clients/:id/secrets/:secretId — revoke a client secret POST /v1/auth/admin/keys/rotate — rotate the signing key pair GET /v1/auth/admin/keys — list active signing keys POST /v1/auth/scopes/register — register a new OAuth scope GET /v1/auth/scopes — list registered scopes

Database tables

SigningKey — RSA key pairs used to sign JWTs (active / retired) ApiClient — registered OAuth clients with metadata and org association ApiClientSecret — hashed secrets associated with clients RegisteredScope — platform-wide scope registry

Events

auth.client.revoked — emit — published to auth.events channel when a client secret is revoked auth.client.updated — emit — published to auth.events channel when client metadata changes auth.key.rotated — emit — published to auth.events channel when a signing key is rotated

Dependencies

  • Redis — event publishing to auth.events channel via @sa-platform/common RedisService
  • MySQL — primary store for clients, keys and scopes, via Prisma 7 driver-adapter pattern

Where to learn more