Once an external request passes the API gateway, most microservice estates lose track of who the request is for and what it was allowed to do, so internal services either trust each other blindly or pass the user's access token deeper than it should ever go. Both choices fail internal zero trust: a compromised service can call any other service with any parameters, and a stolen access token works anywhere inside. OAuth Transaction Tokens (Txn-Tokens), an IETF OAuth working group draft, give every internal hop a short-lived, signed, immutable statement of the subject, the transaction's purpose and its context, issued by a central Transaction Token Service. This guide explains the token format, how it is requested and propagated, the security rules, deployment choices and monitoring. It is for platform, API and IAM engineers running service-to-service architectures, including platforms where AI agents trigger internal calls.
Key takeaways
- A Txn-Token describes the transaction, not the caller's credentials. The draft says Txn-Tokens cannot authenticate a workload; you still need workload authentication such as mTLS or SPIFFE between services.
- The draft is close to IESG submission but not final. As checked on 27 October 2026, draft-ietf-oauth-transaction-tokens-11 (30 July 2026) is at working group consensus, waiting for write-up, with an IESG submission milestone of December 2026.
- Stop sending access tokens inward. The gateway exchanges the inbound access token for a Txn-Token, and the access token must not be embedded in it.
- Lifetimes are minutes or less and there is no refresh. A Txn-Token lives for the duration of the call chain; replacement tokens may narrow, never widen, what is allowed.
- One trust domain only. The
audclaim names the trust domain and the token must not be accepted outside it; for cross-domain calls the draft points to identity chaining.
The problem inside the call chain
A typical request enters through a gateway with an OAuth access token, then fans out across many internal workloads: an orders service calls payments, which calls a ledger, which calls a fraud model. Three patterns are common today, each with a weakness:
- Forward the external access token: every internal service can replay it externally and internally, and its scope is usually broader than any one internal call needs.
- Trust the network: anything inside the mesh may call anything; a compromised workload can invoke the ledger with any account number.
- Custom headers with user IDs: unsigned, easily forged, and different in every team's code.
The draft's stated aims are to reduce unauthorised workload invocation, impersonation, parameter tampering and reuse of stolen access tokens inside a trust domain. It covers both externally triggered requests and requests started inside the domain, such as batch jobs. See the Microservices Security Guide for the wider service-to-service picture.
Terms and architecture
| Term | Meaning in draft -11 |
|---|---|
| Workload | A running instance of software, such as a microservice or managed database |
| Trust domain | Systems sharing security controls and policies, reached only through published interfaces |
| External endpoint | A published interface, often a gateway, that starts invocations inside the domain |
| Call chain | All workload invocations made to complete one transaction |
| Txn-Token | Short-lived signed JWT carrying immutable information about the caller, call parameters and context |
| Transaction Token Service (TTS) | Issues Txn-Tokens; each trust domain has exactly one logical TTS |
The flow is: the external endpoint authenticates the inbound request, asks the TTS for a Txn-Token, and calls the first internal workload with it. Each workload verifies the token, makes its authorisation decision using the token's claims, and forwards the same token unmodified on outbound calls. The TTS is where policy about what each transaction may do is set once.
Inside a Txn-Token
The JWT header typ must be txntoken+jwt, and kid should be supported for key rotation.
| Claim | Status | Purpose |
|---|---|---|
aud | Required | The trust domain where the token is valid |
iat, exp | Required | Issue and expiry times |
txn | Required | Unique transaction identifier, aligned with RFC 8417; the natural correlation ID for logs |
sub | Required | Principal of the transaction, unique within the trust domain |
scope | Required | Narrow purpose of the transaction set by the TTS, which need not match the external scope |
req_wl | Required | The workload that requested the token |
tctx | Recommended | Transaction context: immutable authorisation details, for example the account and amount of a payment |
rctx | Recommended | Request context: environmental details such as originating IP address or authentication method |
iss | Optional | Signer, useful when signing keys are not predetermined |
The value of tctx is what makes parameter tampering detectable: if the payments service sees a ledger request whose account differs from the account in tctx, it can refuse. Recipients must ignore claims they do not understand, so you can add domain-specific claims, but agree them centrally.
Requesting and propagating Txn-Tokens
The request is an RFC 8693 token exchange profile. The requesting workload posts to the TTS token endpoint with:
- grant_type:
urn:ietf:params:oauth:grant-type:token-exchange. - requested_token_type:
urn:ietf:params:oauth:token-type:txn_token. - audience: the trust domain name.
- scope: the transaction's purpose.
- subject_token and subject_token_type: typically the inbound access token (never a refresh token); the draft also defines a self-signed JWT type (
urn:ietf:params:oauth:token-type:self_signed) and an unsigned JSON type (urn:ietf:params:oauth:token-type:unsigned_json) for internally started transactions. - request_context and request_details (recommended): JSON objects the TTS uses, with its own data, to build
rctxandtctx.
The response returns the Txn-Token in access_token with token_type N_A and issued_token_type of the Txn-Token type, and never a refresh token.
Propagation: Txn-Tokens travel in the HTTP header Txn-Token, exactly one per request, and must not be sent in the Authorization header. A receiving workload checks the signature, checks that aud matches its trust domain and checks expiry. Outbound calls forward the token unchanged.
Replacement: a workload can present a Txn-Token as the subject token to get a replacement, for example to add an asserted value or narrow permissions before calling a less trusted service. The replacement must keep txn, sub and aud, must not expand permitted actions, and cannot be issued from an expired token. The number of replacements should be limited.
Worked example: a payment call chain
A customer's mobile app calls POST /payments with an access token carrying the scope payments:write. The illustration below uses the draft's mechanisms; claim values are examples, not normative.
- Gateway: validates the access token, then requests a Txn-Token with
audienceset to the trust domain (for examplepayments.internal.example),scopepayment.initiate, the access token as subject token,request_detailsholding the source account, payee and amount, andrequest_contextholding the client IP and authentication method. - TTS: checks that the gateway workload may request this scope, that
payment.initiatedoes not exceedpayments:write, and issues a token withsubset to the customer's internal identifier, a freshtxn,req_wlnaming the gateway,tctxholding the account, payee and amount, and an expiry a minute or two away. - Payments service: receives the request with the
Txn-Tokenheader over mTLS, verifies the token and confirms the body's account and amount matchtctx. - Ledger service: receives the same token, verifies it, and posts the debit only for the account in
tctx. A compromised payments service that changes the amount or account is refused. - Fraud model: uses
rctx(IP, authentication method) as model input without ever seeing the customer's access token. - Audit: every service logs the same
txn, so the investigation of a disputed payment pulls one identifier across all logs.
Note what the example avoids: no internal service holds a token that works at the public API, and no service can widen the transaction beyond what the gateway and TTS approved.
Security rules from the draft
| Rule | Practical effect |
|---|---|
| Txn-Tokens are not replay-resistant | Keep lifetimes short; optionally track txn values to spot reuse where state allows |
| No refresh tokens to request them, none in responses | Long-running jobs request fresh short tokens rather than holding one |
| Do not embed the inbound access token | Internal services never see a credential usable at the edge; the TTS may check revocation via RFC 7662 introspection |
| Requested scope must not exceed the original token's | If the original scope cannot be determined, the TTS must reject the request |
| Txn-Tokens are not credentials or access tokens | Authenticate workloads separately: mTLS (RFC 8705), SPIFFE or WIMSE mechanisms |
| Mutual authentication between workloads and TTS | Workloads verify the TTS over HTTPS; the TTS authenticates workloads, preferably with asymmetric methods |
| Protect TTS configuration | Workloads load the TTS endpoint and keys from trusted, change-controlled sources |
| Do not log tokens verbatim | Log a hash, or the payload without the signature, and mind personal data such as IP addresses |
The TTS is a high-value target: its signing key lets an attacker forge any transaction for any subject in the domain. Run it with the same rigour as an authorisation server, keep keys in a KMS or HSM, and be selective about which workloads may request tokens and which claims each may receive. See the SPIFFE and SPIRE Guide and the WIMSE Workload Identity Architecture Guide for the workload authentication layer that must sit underneath.
Where Txn-Tokens fit among related patterns
| Pattern | Scope | Use with Txn-Tokens? |
|---|---|---|
| mTLS or SPIFFE workload identity | Authenticates the calling workload | Yes, required underneath: answers "which service is calling" |
| RFC 8693 token exchange for downstream access tokens | Gets an audience-specific access token for one service | Alternative for a few hops; Txn-Tokens scale better across long chains. See the OAuth Token Exchange and Delegation Guide |
| Identity chaining | Crossing to another trust domain's authorisation server | Yes, at the edge of the domain. See the OAuth Identity and Authorization Chaining Across Domains Guide |
| Service mesh authorisation policy | Which service may call which endpoint | Complementary: mesh policy on caller identity, service logic on tctx. See the Service Mesh Security Guide |
| Externalised authorisation (PDP) | Fine-grained decisions per request | Yes: Txn-Token claims become PDP subject and context inputs. See the OpenID AuthZEN Authorization API Guide |
Small estates with a handful of services may get most of the value from audience-restricted downstream tokens and mTLS. Large estates with deep call graphs, multiple languages and agent-triggered workflows benefit most, because one TTS policy replaces many per-team token handling choices. For AI agents, a Txn-Token lets every internal tool service see the original user and the narrow purpose of the agent's request rather than a broad agent credential.
How to implement
- Establish workload identity first. Every workload that will request or verify Txn-Tokens needs an authenticated identity (SPIFFE IDs, mesh certificates or platform workload identity).
- Stand up the TTS in a test environment, with KMS-held signing keys, a published JWKS and a short default lifetime.
- Define scopes and context for one transaction type: what goes in
scope,tctxandrctx, and which workloads may request it. - Integrate the gateway: exchange the inbound access token for a Txn-Token and stop forwarding the access token inward.
- Verify in observe mode: downstream services validate the
Txn-Tokenheader and log results without rejecting, for two to four weeks. - Enforce: reject missing, expired, wrong-domain or tampered tokens, and start checking request parameters against
tctx. - Extend to internally started jobs using the self-signed subject token type, with tight TTS policy on which workloads may use it.
- Rollback: switch services back to observe mode by configuration; do not re-enable inward forwarding of access tokens.
Detection and measurement
- TTS logs: every issuance and denial with
req_wl,sub,scope,txnand the policy rule. - Workload logs: verification outcome and
txnon every request, so a whole call chain can be reconstructed from one identifier. - Alerts: verification failures by service, requests where parameters do not match
tctx, issuance to an unexpectedreq_wl, the sametxnappearing outside its expected window, and anyAuthorizationheader carrying an external access token on internal hops.
Metrics: percentage of internal calls carrying a valid Txn-Token; number of services still receiving the external access token; median Txn-Token lifetime; rate of tctx mismatches; TTS p99 latency and availability, since every transaction now depends on it.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | AC-3 Access Enforcement; AC-4 Information Flow Enforcement; AC-16 Security and Privacy Attributes; IA-9 Service Identification and Authentication; SC-8 Transmission Confidentiality and Integrity; AU-3 Content of Audit Records | Signed attributes bound to each request and traceable records |
| NIST CSF 2.0 | PR.AA-03, PR.AA-05; PR.DS-02 | Service authentication, least privilege, data-in-transit integrity |
| ISO/IEC 27001:2022 Annex A | 8.3 Information access restriction; 8.15 Logging; 8.26 Application security requirements | Per-request access restriction designed into applications |
| CIS Controls v8.1 | Control 6 Access Control Management; Control 16 Application Software Security | Access control built into service design |
| MITRE ATT&CK | T1550.001 Application Access Token; T1528 Steal Application Access Token | Stolen access tokens are no longer accepted on internal hops |
Common failure patterns
- Treating the Txn-Token as authentication. Without workload authentication, any process that obtains a token can call services with it.
- Letting any workload request any scope. A permissive TTS lets a compromised service mint tokens for transactions it never handles.
- Logging the full token in traces and API logs, creating replayable tokens and personal data in observability tools. See the JWT and Session Tokens in Code and Logs Guide.
- Verifying but not using
tctx. Checking the signature alone leaves parameter tampering possible. - Long lifetimes for batch jobs instead of short tokens requested per unit of work, which the draft advises against.
- A TTS without high availability, which turns a security control into an outage and drives teams to bypass it.
Practitioner checklist
- Confirm every workload has an authenticated identity before introducing Txn-Tokens.
- Run one logical TTS per trust domain with KMS-held keys and a published JWKS.
- Define scope,
tctxandrctxcontents per transaction type. - Exchange inbound access tokens at the gateway and stop forwarding them inward.
- Propagate tokens only in the
Txn-Tokenheader, unmodified. - Validate signature,
aud, expiry andtctxin every service. - Keep lifetimes to minutes or less and limit replacements.
- Log
txnand outcomes, never whole tokens. - Monitor TTS latency and availability as a tier-one dependency, with capacity tested at peak transaction rates.
- Restrict which workloads may use self-signed or unsigned subject tokens for internally started transactions.
- Track the draft's progress to RFC and re-check claim names on upgrade.
Standards and references
- IETF: Transaction Tokens (draft-ietf-oauth-transaction-tokens)
- IETF: RFC 8693 OAuth 2.0 Token Exchange
- IETF: OAuth Identity and Authorization Chaining Across Domains (draft-ietf-oauth-identity-chaining)
- IETF: RFC 7523 JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants
- OpenID Foundation: Authorization API 1.0
Related NHI Mgmt Group resources: OAuth Token Exchange and Delegation Guide · Microservices Security Guide · SPIFFE and SPIRE Guide · NIST SP 800-207A Zero Trust for Cloud-Native Applications Guide