Problem
Our services call each other: one asks the others to erase a person's data, billing tells accounts which plan a subscription gives, the model service calls its tools, the gateway hands a person's request to the service that answers it. The service that receives such a call decides what the caller may do from who the caller is.
The platform's rule is that services never verify credentials themselves; the gateway does, once, and the services trust what it forwards. This RFC describes how that rule covers calls between our own services: what each service holds to prove who it is, what the gateway checks, and how a service acting for a person passes that person on.
Proposal
Every service has its own credential. Each service is registered with our identity provider as a machine client named after the service. Its secret lives only in the platform's secret store, created by an operator task, never in a file or the repository. The service exchanges it for a short-lived signed token (the OAuth 2.0 client credentials grant, RFC 6749 section 4.4) and keeps it in memory, renewing it before it expires.
The gateway verifies it. On calls between services the gateway checks the token's signature, issuer, audience and expiry, and forwards to the receiving service only the identity it verified, the same way it does for calls from outside. Service tokens carry an audience of their own, so they are accepted only between services, and tokens issued for the public API are not accepted there.
Acting for a person is a granted right. Where a service acts on behalf of the person who made the request, it passes that person's verified identity along with its own token. Only services granted that right in the gateway's configuration may do so; every other service only ever speaks as itself.
Rolled out without breaking a call. The gateway first records the verified caller of every call between services (who, never content), the services then present their tokens, and the gateway enforces the check once every caller does. Each step is its own reviewed change.
What stays the same. Calls from outside are untouched. Services read the caller from the same place in the same shape, so no handler changes, and tests still boot services directly.
Trade-off. The identity provider becomes a dependency of calls between services: a long outage of its token endpoint would stop them once cached tokens expire. Mutual TLS would avoid that, but needs a certificate authority, rotation and new client code in every service, and still a second mechanism for acting on a person's behalf. Reusing the token verification the gateway already runs is the smaller change for the same guarantee.
Status log
- 2026-10-07: Opened. Design chosen: per-service credentials, verified by the gateway.
- 2026-10-07: Step 1 (the gateway records the verified caller) live. Step 2 (every calling service presents its own credential) written.