Join our Newsletter — 33% off our NHI Course
Home› Guides› OAuth Transaction Tokens (Txn-Tokens) Guide: Preserving Context Inside…
Guide Authorisation

OAuth Transaction Tokens (Txn-Tokens) Guide: Preserving Context Inside Service Call Chains

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

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 aud claim 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

TermMeaning in draft -11
WorkloadA running instance of software, such as a microservice or managed database
Trust domainSystems sharing security controls and policies, reached only through published interfaces
External endpointA published interface, often a gateway, that starts invocations inside the domain
Call chainAll workload invocations made to complete one transaction
Txn-TokenShort-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.

ClaimStatusPurpose
audRequiredThe trust domain where the token is valid
iat, expRequiredIssue and expiry times
txnRequiredUnique transaction identifier, aligned with RFC 8417; the natural correlation ID for logs
subRequiredPrincipal of the transaction, unique within the trust domain
scopeRequiredNarrow purpose of the transaction set by the TTS, which need not match the external scope
req_wlRequiredThe workload that requested the token
tctxRecommendedTransaction context: immutable authorisation details, for example the account and amount of a payment
rctxRecommendedRequest context: environmental details such as originating IP address or authentication method
issOptionalSigner, 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 rctx and tctx.

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.

  1. Gateway: validates the access token, then requests a Txn-Token with audience set to the trust domain (for example payments.internal.example), scope payment.initiate, the access token as subject token, request_details holding the source account, payee and amount, and request_context holding the client IP and authentication method.
  2. TTS: checks that the gateway workload may request this scope, that payment.initiate does not exceed payments:write, and issues a token with sub set to the customer's internal identifier, a fresh txn, req_wl naming the gateway, tctx holding the account, payee and amount, and an expiry a minute or two away.
  3. Payments service: receives the request with the Txn-Token header over mTLS, verifies the token and confirms the body's account and amount match tctx.
  4. 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.
  5. Fraud model: uses rctx (IP, authentication method) as model input without ever seeing the customer's access token.
  6. 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

RulePractical effect
Txn-Tokens are not replay-resistantKeep lifetimes short; optionally track txn values to spot reuse where state allows
No refresh tokens to request them, none in responsesLong-running jobs request fresh short tokens rather than holding one
Do not embed the inbound access tokenInternal 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'sIf the original scope cannot be determined, the TTS must reject the request
Txn-Tokens are not credentials or access tokensAuthenticate workloads separately: mTLS (RFC 8705), SPIFFE or WIMSE mechanisms
Mutual authentication between workloads and TTSWorkloads verify the TTS over HTTPS; the TTS authenticates workloads, preferably with asymmetric methods
Protect TTS configurationWorkloads load the TTS endpoint and keys from trusted, change-controlled sources
Do not log tokens verbatimLog 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.

PatternScopeUse with Txn-Tokens?
mTLS or SPIFFE workload identityAuthenticates the calling workloadYes, required underneath: answers "which service is calling"
RFC 8693 token exchange for downstream access tokensGets an audience-specific access token for one serviceAlternative for a few hops; Txn-Tokens scale better across long chains. See the OAuth Token Exchange and Delegation Guide
Identity chainingCrossing to another trust domain's authorisation serverYes, at the edge of the domain. See the OAuth Identity and Authorization Chaining Across Domains Guide
Service mesh authorisation policyWhich service may call which endpointComplementary: mesh policy on caller identity, service logic on tctx. See the Service Mesh Security Guide
Externalised authorisation (PDP)Fine-grained decisions per requestYes: 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

  1. 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).
  2. Stand up the TTS in a test environment, with KMS-held signing keys, a published JWKS and a short default lifetime.
  3. Define scopes and context for one transaction type: what goes in scope, tctx and rctx, and which workloads may request it.
  4. Integrate the gateway: exchange the inbound access token for a Txn-Token and stop forwarding the access token inward.
  5. Verify in observe mode: downstream services validate the Txn-Token header and log results without rejecting, for two to four weeks.
  6. Enforce: reject missing, expired, wrong-domain or tampered tokens, and start checking request parameters against tctx.
  7. Extend to internally started jobs using the self-signed subject token type, with tight TTS policy on which workloads may use it.
  8. 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, txn and the policy rule.
  • Workload logs: verification outcome and txn on 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 unexpected req_wl, the same txn appearing outside its expected window, and any Authorization header 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

FrameworkReferenceRelevance
NIST SP 800-53 Rev 5AC-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 RecordsSigned attributes bound to each request and traceable records
NIST CSF 2.0PR.AA-03, PR.AA-05; PR.DS-02Service authentication, least privilege, data-in-transit integrity
ISO/IEC 27001:2022 Annex A8.3 Information access restriction; 8.15 Logging; 8.26 Application security requirementsPer-request access restriction designed into applications
CIS Controls v8.1Control 6 Access Control Management; Control 16 Application Software SecurityAccess control built into service design
MITRE ATT&CKT1550.001 Application Access Token; T1528 Steal Application Access TokenStolen 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, tctx and rctx contents per transaction type.
  • Exchange inbound access tokens at the gateway and stop forwarding them inward.
  • Propagate tokens only in the Txn-Token header, unmodified.
  • Validate signature, aud, expiry and tctx in every service.
  • Keep lifetimes to minutes or less and limit replacements.
  • Log txn and 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.