Skip to content
Kisum • Documentation

Service-to-service authentication

Service-to-service authentication

Section titled “Service-to-service authentication”

Kisum backend services use short-lived Auth-issued RS256 service tokens for supported machine-to-machine calls. This rollout is additive: existing destination-specific internal keys remain valid until staging observation and an explicit second deployment retire them.

Canonical wire contract

Section titled “Canonical wire contract”
  • Auth issues tokens through POST /auth/service-token after validating the caller name, caller secret, and requested audience against SERVICE_CLIENTS.
  • Tokens use the existing Auth signing key and JWKS, expire after about 15 minutes, and contain sub: svc:<caller>, the destination aud, and token_use: service.
  • Callers send the token in X-Service-Token. Authorization remains reserved for a forwarded user access token when user context is also required.
  • Destinations validate signature, issuer, expiry, audience, service subject, and token use. Any invalid machine credential fails closed with 401.
  • Caller helpers cache tokens, renew before expiry, invalidate after 401, and retry once.

Current rollout scope

Section titled “Current rollout scope”
CallerDestinationStatus
AuthCoreImplemented behind S2S_TOKENS_ENABLED
PromotersArtists, Venues, MusicDataImplemented behind S2S_TOKENS_ENABLED
ArtistsCore, VenuesImplemented behind S2S_TOKENS_ENABLED
VenuesArtists, PromotersImplemented behind S2S_TOKENS_ENABLED
Promoters Amplify news functionMusicDataImplemented behind S2S_TOKENS_ENABLED

Artists, Venues, Core, MusicData, and Promoters accept X-Service-Token alongside their existing static internal keys. Admin and Finance are not part of this rollout and continue using their documented service-specific static keys.

Configuration and rollout

Section titled “Configuration and rollout”
  • Auth: configure SERVICE_CLIENTS and keep SERVICE_TOKEN_TTL near 15 minutes.
  • Callers: configure AUTH_SERVICE_SECRET; leave S2S_TOKENS_ENABLED=false until staging is ready.
  • Deploy 1: enable tokens additively and observe token-fetch and 401 metrics for one to two days.
  • Deploy 2: only after successful observation, remove static-key acceptance and rotate/delete retired secrets.

Never put service secrets or tokens in source files, browser code, logs, query strings, or user-facing error responses.