Transaction Tokens
draft-ietf-oauth-transaction-tokens-11
| Document | Type | Active Internet-Draft (oauth WG) | |
|---|---|---|---|
| Authors | Atul Tulshibagwale , George Fletcher , Pieter Kasselman | ||
| Last updated | 2026-08-04 (Latest revision 2026-07-30) | ||
| Replaces | draft-oauth-transaction-tokens | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | In WG Last Call | |
| Associated WG milestone |
|
||
| Document shepherd | Rifaat Shekh-Yusef | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | rifaat.s.ietf@gmail.com |
draft-ietf-oauth-transaction-tokens-11
oauth A. Tulshibagwale
Internet-Draft CrowdStrike
Intended status: Standards Track G. Fletcher
Expires: 31 January 2027 Practical Identity LLC
P. Kasselman
Defakto Security
30 July 2026
Transaction Tokens
draft-ietf-oauth-transaction-tokens-11
Abstract
Transaction Tokens (Txn-Tokens) are designed to maintain and
propagate user identity, workload identity and authorization context
throughout the Call Chain within a trusted domain during the
processing of external requests (e.g. such as API calls) or requests
initiated internally within the Trust Domain. Txn-Tokens ensure that
this context is preserved throughout the Call Chain thereby enhancing
security and consistency in complex, multi-service architectures.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://drafts.oauth.net/oauth-transaction-tokens/draft-ietf-oauth-
transaction-tokens.html. Status information for this document may be
found at https://datatracker.ietf.org/doc/draft-ietf-oauth-
transaction-tokens/.
Source for this draft and an issue tracker can be found at
https://github.com/oauth-wg/oauth-transaction-tokens.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Tulshibagwale, et al. Expires 31 January 2027 [Page 1]
Internet-Draft Txn-Tokens July 2026
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 31 January 2027.
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. What are Transaction Tokens? . . . . . . . . . . . . . . . . 5
4.1. Authorization Context . . . . . . . . . . . . . . . . . . 6
5. Creating Txn-Tokens . . . . . . . . . . . . . . . . . . . . . 6
5.1. Creation . . . . . . . . . . . . . . . . . . . . . . . . 6
6. Txn-Token Lifetime . . . . . . . . . . . . . . . . . . . . . 7
7. Benefits of Txn-Tokens . . . . . . . . . . . . . . . . . . . 7
8. Txn-Token Issuance and Usage Flows . . . . . . . . . . . . . 8
8.1. Basic Flow . . . . . . . . . . . . . . . . . . . . . . . 8
8.2. Internally Initiated Txn-Token Flow . . . . . . . . . . . 9
9. Txn-Token Format . . . . . . . . . . . . . . . . . . . . . . 11
9.1. JWT Header . . . . . . . . . . . . . . . . . . . . . . . 11
9.2. JWT Body Claims . . . . . . . . . . . . . . . . . . . . . 11
9.2.1. Scope claim . . . . . . . . . . . . . . . . . . . . . 12
9.2.2. Request Context . . . . . . . . . . . . . . . . . . . 12
9.2.3. Transaction Context . . . . . . . . . . . . . . . . . 13
9.2.4. Example . . . . . . . . . . . . . . . . . . . . . . . 13
10. Txn-Token Service (TTS) . . . . . . . . . . . . . . . . . . . 14
11. Requesting Txn-Tokens . . . . . . . . . . . . . . . . . . . . 15
11.1. Txn-Token Request . . . . . . . . . . . . . . . . . . . 15
11.2. Subject Token Types . . . . . . . . . . . . . . . . . . 17
11.2.1. Self-Signed Subject Token Type . . . . . . . . . . . 17
11.2.2. Unsigned JSON Object Subject Token Type . . . . . . 18
Tulshibagwale, et al. Expires 31 January 2027 [Page 2]
Internet-Draft Txn-Tokens July 2026
11.3. Txn-Token Request Processing . . . . . . . . . . . . . . 18
11.4. Txn-Token Response . . . . . . . . . . . . . . . . . . . 19
11.5. Mutual Authentication of the Txn-Token Request . . . . . 20
12. Using Txn-Tokens . . . . . . . . . . . . . . . . . . . . . . 20
12.1. "Txn-Token" HTTP Header . . . . . . . . . . . . . . . . 21
12.2. Txn-Token Validation . . . . . . . . . . . . . . . . . . 21
13. Security Considerations . . . . . . . . . . . . . . . . . . . 21
13.1. Txn-Token Replay Risks . . . . . . . . . . . . . . . . . 21
13.2. Unique Transaction Identifier . . . . . . . . . . . . . 22
13.3. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 22
13.4. Access Tokens . . . . . . . . . . . . . . . . . . . . . 22
13.5. Subject Token Types . . . . . . . . . . . . . . . . . . 23
13.6. Scope Processing . . . . . . . . . . . . . . . . . . . . 23
13.7. TTS Discovery . . . . . . . . . . . . . . . . . . . . . 23
13.8. Workload Configuration Protection . . . . . . . . . . . 23
13.9. TTS Authentication . . . . . . . . . . . . . . . . . . . 24
13.10. TTS Issuance Policies . . . . . . . . . . . . . . . . . 24
13.11. TTS Key Rotation . . . . . . . . . . . . . . . . . . . . 24
13.12. Transaction Tokens Are Not Authentication Credentials . 24
13.13. Transaction Tokens Are Not OAuth 2.0 Access Tokens . . . 24
13.14. Unknown subject_token scope . . . . . . . . . . . . . . 25
13.15. Txn-Token as a subject_token . . . . . . . . . . . . . . 25
13.16. Determining signing keys . . . . . . . . . . . . . . . . 26
14. Preserving transaction context across Trust Domains . . . . . 26
15. Privacy Considerations . . . . . . . . . . . . . . . . . . . 26
15.1. Handling of Personal Information . . . . . . . . . . . . 26
15.2. Logging . . . . . . . . . . . . . . . . . . . . . . . . 26
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
16.1. OAuth URI Subregistry Contents . . . . . . . . . . . . . 27
16.2. JWT Claims Registry Contents . . . . . . . . . . . . . . 27
16.3. IANA Media Type Registration Contents . . . . . . . . . 28
16.4. HTTP Header . . . . . . . . . . . . . . . . . . . . . . 29
17. References . . . . . . . . . . . . . . . . . . . . . . . . . 29
17.1. Normative References . . . . . . . . . . . . . . . . . . 29
17.2. Informative References . . . . . . . . . . . . . . . . . 32
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33
Document History . . . . . . . . . . . . . . . . . . . . . . . . 33
Since Draft 10 . . . . . . . . . . . . . . . . . . . . . . . . 33
Since Draft 09 . . . . . . . . . . . . . . . . . . . . . . . . 33
Since Draft 08 . . . . . . . . . . . . . . . . . . . . . . . . 33
Since Draft 07 . . . . . . . . . . . . . . . . . . . . . . . . 34
Since Draft 06 . . . . . . . . . . . . . . . . . . . . . . . . 35
Since Draft 05 . . . . . . . . . . . . . . . . . . . . . . . . 37
Since Draft 04 . . . . . . . . . . . . . . . . . . . . . . . . 37
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37
Tulshibagwale, et al. Expires 31 January 2027 [Page 3]
Internet-Draft Txn-Tokens July 2026
1. Introduction
Modern computing architectures often consist of multiple
independently running components, referred to in this document as
workloads. In many deployments, an external invocation through an
interface such as an API results in the invocation of multiple
internal workloads in order to process the request. These workloads
often execute in virtually or physically isolated networks. Such
networks, and the workloads operating within them, can be compromised
through software supply chain attacks, privileged user compromise,
malicious insiders, software defects, or other attacks. Such
compromise can enable unauthorized actions, including
* Invocation of workloads in the absence of a valid transaction.
* Arbitrary user or workload impersonation.
* Parameter modification or augmentation.
* Theft of tokens used to convey authorization context (e.g. OAuth
2.0 access tokens).
Transaction Tokens (Txn-Tokens) are intended to reduce these risks by
carrying user or workload identity, along with authorization and
request context, in short-lived, signed JWTs that are bound to
specific transactions and propagated throughout the Call Chain within
a Trust Domain. The authorization and request context include
parameters of the original call, environmental attributes such as the
IP address of the original caller, user and workload identity
information and other information that is expected to remain
consistent across subsequent workload invocations, including
information added within the Trust Domain after the initial request.
Downstream workloads use Txn-tokens to apply authorization decisions
based on this context within a specific transaction. Txn-Tokens are
cryptographically protected, enabling downstream workloads to detect
unauthorized modification of this information. Txn-Tokens reduce
risk by making it harder for an attacker to invoke workloads outside
an authorized transaction, impersonate users or workloads within a
transaction, modify request context for a transaction, or rely on
stolen access tokens alone.
Txn-Tokens apply both to transactions initiated by an external event,
such as an Internet-facing API invocation, and to transactions
initiated from within the Trust Domain.
Tulshibagwale, et al. Expires 31 January 2027 [Page 4]
Internet-Draft Txn-Tokens July 2026
2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. Terminology
Workload: A running instance of software executing for a specific
purpose. Examples of workloads include containerized
microservices, monolithic services and infrastructure services
such as managed databases.
Trust Domain: A logical grouping of systems that share a common set
of security controls and policies. In practice this may include a
virtually or physically separated network, which contains two or
more workloads. The workloads within a Trust Domain may be
invoked only through published interfaces.
External Endpoint: A published interface to a Trust Domain that
results in the invocation of a workload within the Trust Domain.
In practice, the external endpoint may be accessed through a
gateway service as described in the WIMSE architecture
[I-D.ietf-wimse-arch].
Call Chain: The set of invocations across all workloads invoked to
complete the requested transaction.
Transaction Token (Txn-Token): A signed JWT with a short lifetime,
providing immutable information about the user or workload,
certain parameters of the call, and specific contextual attributes
of the call. The Txn-Token is used to authorize subsequent calls
in the Call Chain.
Transaction Token Service (TTS): A special service within the Trust
Domain that issues Txn-Tokens to requesting workloads. Each Trust
Domain using Txn-Tokens MUST have exactly one logical TTS.
4. What are Transaction Tokens?
Txn-Tokens are short-lived, signed JWTs [RFC7519] that assert the
identity of a user or a workload and an authorization context. The
authorization context provides information expected to remain
constant during the execution of the transaction as it passes through
the Call Chain.
Tulshibagwale, et al. Expires 31 January 2027 [Page 5]
Internet-Draft Txn-Tokens July 2026
4.1. Authorization Context
Authorization context includes information used for authorization,
accounting and auditing purposes and often contains information about
the request being made. A key aspect of the authorization context is
the intent or purpose of the transaction, which should be as narrowly
defined as possible for the given deployment. A narrowly scoped,
short-lived, transaction token reduces the attack surface of captured
and replayed transaction tokens.
5. Creating Txn-Tokens
5.1. Creation
Txn-Tokens are typically created when a workload is invoked using an
endpoint that is externally visible, and is authorized using a
separate mechanism, such as an OAuth [RFC6749] access token. The
externally visible endpoint exchanges the external authorization
token for a transaction token before sending it to the workload. The
transaction token may be obtained through a local interface, or it
may be requested from a remote server.
If the transaction token request is made via HTTP to a remote server,
it MUST use [RFC8693] as described in this specification. To do
this, it invokes a special Token Service (the Transaction Token
Service (TTS)) and provides context that is sufficient for the TTS to
generate a Txn-Token.
The context information provided to the TTS MUST include:
* The identification of the Trust Domain in which the issued Txn-
Token is valid.
* A token which identifies the subject of the Txn-Token (e.g. an
OAuth access token, a self-issued JWT, etc).
* The desired authorization scope for the issued Txn-Token.
Additional contextual information MAY be provided such as:
* Parameters that are required to be integrity protected for the
duration of this call.
* Additional context, such as the incoming IP address, User Agent
information, or other context that can help the TTS to issue the
Txn-Token.
Tulshibagwale, et al. Expires 31 January 2027 [Page 6]
Internet-Draft Txn-Tokens July 2026
The TTS responds to a successful invocation by generating a Txn-
Token. The calling workload then uses the Txn-Token to authorize its
calls to subsequent workloads.
If the requesting service does not have an inbound token that it can
use in its request to the TTS, it MAY generate a self-signed JWT and
present that in the request in place of the external authorization
token. This can be the case when the external authentication does
not use an access token or when the requesting service is initiating
a scheduled internal request for itself or on behalf of a user of the
system.
6. Txn-Token Lifetime
Txn-Tokens are expected to be short-lived (on the order of minutes or
less), and as a result MUST be used only for the expected duration of
an external or internal invocation. If the token or other credential
(e.g. self-signed JWT) presented to the TTS when requesting a Txn-
Token has an expiration time, then the TTS MUST NOT issue a Txn-Token
if the expiration time has passed. The lifetime of the Txn-Token
itself MAY exceed the expiration time of the presented token, subject
to the policy of the TTS. The TTS SHOULD assess whether the Txn-
Token’s assigned lifetime and transaction binding adequately mitigate
the risks of a Txn-Token lifetime that exceeds the presented subject
token’s expiration time. If a long-running process such as a batch
or offline task is involved, the mechanism used to perform the
external or internal invocation still results in a short-lived Txn-
Token (see Section 13.1).
7. Benefits of Txn-Tokens
Txn-Tokens prevent unauthorized invocations by allowing a workload to
independently verify the identity of the user or workload that
initiated an external call, as well as any contextual information
relevant to processing that call. This results in the following
benefits:
* Short-lived, Txn-Tokens, bound to a single transaction, reduce
replay risk.
* Narrowly scoped Txn-Tokens limit lateral movement and blast
radius.
* Signed Txn-Tokens protect the original call context and identity
from modification along the Call Chain.
* Independent verification at each workload helps prevent
unauthorized invocation.
Tulshibagwale, et al. Expires 31 January 2027 [Page 7]
Internet-Draft Txn-Tokens July 2026
* Restricting which workloads can obtain Txn-Tokens limits exposure
from compromised or untrusted services, including some SBOM-
related attack paths.
8. Txn-Token Issuance and Usage Flows
8.1. Basic Flow
Figure 1 shows the basic flow of how Txn-Tokens are used in a multi-
workload environment.
1 +--------------+ 2 +--------------+
--------->│ │---------->│ │
│ External │ │ Txn-Token │
8 │ Endpoint │ 3 │ Service │
<---------│ │<----------│ │
+--------------+ +--------------+
│ ^
4 v │ 7
+--------------+
│ │
│ Internal │
│ Workload │
│ │
+--------------+
│ ^
v │
o
5 o 6
o
│ ^
v │
+--------------+
│ │
│ Internal │
│ Workload │
│ │
+--------------+
Figure 1: Basic Transaction Tokens Architecture
1. External endpoint is invoked using conventional authorization
mechanism such as an OAuth 2.0 Access token.
2. External endpoint provides context and incoming authorization
(e.g., access token) to the TTS.
Tulshibagwale, et al. Expires 31 January 2027 [Page 8]
Internet-Draft Txn-Tokens July 2026
3. TTS mints a Txn-Token that provides immutable context for the
transaction and returns it to the requester.
4. The external endpoint initiates a call to an internal workload
and provides the Txn-Token as authorization.
5. Subsequent calls to other internal workloads use the same Txn-
Token to authorize calls.
6. Responses are provided to calling workloads based on successful
authorization by the invoked workloads.
7. Response provided to external endpoint based on successful
authorization by the invoked workload.
8. External client is provided a response to the external
invocation.
8.2. Internally Initiated Txn-Token Flow
An internal workload may need to initiate a transaction not on the
basis of a current external request, but as part of a scheduled task
or in reaction to a specific condition. The transaction may be
requested on behalf of the identity of the requesting workload or as
an impersonation on behalf of a specific user chosen based on
information accessible to the workload.
Tulshibagwale, et al. Expires 31 January 2027 [Page 9]
Internet-Draft Txn-Tokens July 2026
1 ┌──────────────┐ 2 ┌──────────────┐
│ ├───────────▶ │
│ Internal │ │ Txn-Token │
│ Workload │ 3 │ Service │
┤ ◀───────────│ │
└────┬───▲─────┘ └──────────────┘
│ │
4 │ │ 7
┌────▼───┴─────┐
│ │
│ Internal │
│ Workload │
│ │
└────┬───▲─────┘
│ │
▼ │
o
5 o 6
│ o ▲
│ │
│ │
┌────▼───┴─────┐
│ |
│ Internal │
│ Workload │
│ |
└──────────────┘
Figure 2: Internally Initiated Txn-Token Flow
In the diagram above, steps 5-7 are the same as in Section 8.1.
1. A workload determines that it needs to initiate a request on
behalf of a user in response to a scheduled timer or other
trigger.
2. The internal workload authenticates to the token service and
makes a request for a Txn-Token. The request contains
information about the transaction along with optional additional
authorization credentials.
3. TTS authorizes the requester and then mints a Txn-Token that
provides immutable context for the transaction and returns it to
the requester.
4. The originating workload then contacts another internal workload
and provides the Txn-Token as authorization.
Tulshibagwale, et al. Expires 31 January 2027 [Page 10]
Internet-Draft Txn-Tokens July 2026
9. Txn-Token Format
A Txn-Token is a JSON Web Token [RFC7519] protected by a JSON Web
Signature [RFC7515]. The following describes the required values in
a Txn-Token:
9.1. JWT Header
In the JWT Header:
* The typ Header Parameter MUST be present and MUST have the value
txntoken+jwt.
* Key rotation of the signing key SHOULD be supported through the
use of a kid Header Parameter.
Figure 3 is a non-normative example of the JWT Header of a Txn-Token
{
"typ": "txntoken+jwt",
"alg": "RS256",
"kid": "identifier-to-key"
}
Figure 3: Example: Txn-Token Header
9.2. JWT Body Claims
The body of a Txn-Token is a JWT [RFC7519]. It contains a
combination of existing JWT claims and new claims defined in this
specification as described below. A Txn-Token MAY contain additional
claims not defined in this specification. Recipients of a Txn-Token
MUST ignore any claims they do not understand.
iss: OPTIONAL The iss claim as defined in [RFC7519] is not required
as Txn-Tokens are bound to a single Trust Domain as defined by the
aud claim and often the signing keys are known.
iat: REQUIRED The issued at time of the Txn-Token as defined in
[RFC7519].
aud: REQUIRED This claim, defined in [RFC7519], MUST identify the
Trust Domain in which the Txn-Token is valid. A Txn-Token MUST
NOT be accepted outside the Trust Domain identified by the aud
claim.
exp: REQUIRED Expiry time of the Txn-Token as defined in [RFC7519].
Tulshibagwale, et al. Expires 31 January 2027 [Page 11]
Internet-Draft Txn-Tokens July 2026
txn: REQUIRED A unique transaction identifier as defined in
Section 2.2 of [RFC8417].
sub: REQUIRED This claim represents the principal of the transaction
as defined by Section 4.1.2 of [RFC7519]. The value MUST be
unique within the context of the aud Trust Domain. Note: Unlike
OpenID Connect, the sub claim is NOT associated with the iss
claim.
scope: REQUIRED The scope claim is defined in Section 4.2 of
[RFC8693]. Note that the value of this claim is determined by the
TTS and is not required to match the requested scope nor the scope
in any supplied external token. For additional context please
refer to Section 9.2.1
tctx: RECOMMENDED A JSON object that contains values that remain
immutable throughout the Call Chain. For additional context
please refer to Section 9.2.2
rctx: RECOMMENDED A JSON object that describes the environmental
context of the requested transaction. For additional context
please refer to Section 9.2.3
req_wl: REQUIRED. A string value that identifies the workload that
requested the Txn-Token.
9.2.1. Scope claim
The scope claim captures, as narrowly as possible, the purpose of
this particular transaction. The values used for this claim are
defined by the TTS as representative of the authorization model
defined by the Trust Domain. The value may be literately and
semantically different from, and represent an intent narrower, than a
scope value issued to an external client. How a given deployment
represents the authorization model within the Trust Domain is at its
discretion and not prescribed by this specification.
9.2.2. Request Context
The Txn-Token SHOULD contain an rctx claim. The JSON value of the
rctx claim MAY include any values the TTS determines are relevant to
downstream services that rely on the Txn-Token. For example, this
may include the IP address information of the originating request,
information about the computational entity that requested the Txn-
Token and contextual attributes of the originating request itself.
The following is a non-normative example of an rctx claim initiated
by an external call:
Tulshibagwale, et al. Expires 31 January 2027 [Page 12]
Internet-Draft Txn-Tokens July 2026
{
"rctx": {
"req_ip": "69.151.72.123", // IP address of the originating request
"authn": "face", // from RFC 8176
"transport": "https" // transport method used for the originating request
}
}
9.2.3. Transaction Context
The Txn-Token SHOULD contain an tctx claim. The value of this claim
is a JSON object that contains fields (wherein the value could itself
be an object), which together assert the details that remain
immutable through the Call Chain where this Txn-Token is used.
Txn-Tokens are primarily used to assure identity and context for a
transaction, and the content of this field is a critical part of that
context.
Whereas the rctx field contains environmental values related to the
request, the tctx field contains the actual authorizaton details that
are determined by the TTS. These values are used by services using
the Txn-Token to reliably obtain specific parameters needed to
perform their work. The content of the tctx field is determined by
the TTS and the claims may be computed internally or from parameters
it receives from the service that requests the Txn-Token.
The following is a non-normative example of an tctx claim initiated
by an external call:
{
"tctx": {
"action": "BUY", // parameter of external call
"ticker": "MSFT", // parameter of external call
"quantity": "100", // parameter of external call
"customer_type": { // computed value not present in external call
"geo": "US",
"level": "VIP"
}
}
}
9.2.4. Example
The figure below Figure 4 shows a non-normative example of the JWT
body of a Txn-Token initiated by an external call:
Tulshibagwale, et al. Expires 31 January 2027 [Page 13]
Internet-Draft Txn-Tokens July 2026
{
"iat": 1686536226,
"aud": "trust-domain.example",
"exp": 1686536586,
"txn": "97053963-771d-49cc-a4e3-20aad399c312",
"sub": "d084sdrt234fsaw34tr23t",
"req_wl": "apigateway.trust-domain.example", // the internal entity that requested the Txn-Token
"rctx": {
"req_ip": "69.151.72.123", // env context of external call
"authn": "face" // from RFC 8176
},
"scope" : "trade.stocks",
"tctx": {
"action": "BUY", // parameter of external call
"ticker": "MSFT", // parameter of external call
"quantity": "100", // parameter of external call
"customer_type": { // computed value not present in external call
"geo": "US",
"level": "VIP"
}
}
}
Figure 4: Example: Txn-Token Body
A Txn-Token from an internal request would look much the same except
the rctx and tctx field claims would be populated with information
from the initiating workloads request.
10. Txn-Token Service (TTS)
A Txn-Token Service (TTS) uses [RFC8693] as described in this
specification to issue transaction tokens in response to HTTP
requests. The unique properties of the Txn-Token requests and
responses are described below. The TTS MAY optionally support other
OAuth 2.0 endpoints and features, but that is not a requirement for
it to be a TTS.
Each Trust Domain that uses Txn-Tokens MUST have exactly one logical
TTS.
Tulshibagwale, et al. Expires 31 January 2027 [Page 14]
Internet-Draft Txn-Tokens July 2026
11. Requesting Txn-Tokens
A workload requests a Txn-Token from a TTS. If the transaction token
request is made via HTTP to a remote server, it MUST use [RFC8693] as
described in this specification. Txn-Tokens may be requested for
both externally originating or internally originating requests. This
profile describes how required and optional context can be provided
to the TTS in order for the Txn-Token to be issued. The request to
obtain a Txn-Token using this method is called a Txn-Token Request,
and a successful response is called a Txn-Token Response. The Txn-
Token profile of the OAuth 2.0 Token Exchange [RFC8693] is described
below.
11.1. Txn-Token Request
A workload requesting a Txn-Token provides the TTS with proof of its
identity (client authentication), the purpose of the Txn-Token and
optionally any additional context relating to the transaction being
performed. Most of these elements are provided by the OAuth 2.0
Token Exchange specification and the rest are defined as new
parameters. Additionally, this profile defines a new token type URN
urn:ietf:params:oauth:token-type:txn_token which is used by the
requesting workload to identify that it is requesting the Txn-Token
Response to contain a Txn-Token.
To request a Txn-Token the workload invokes the OAuth 2.0 [RFC6749]
token endpoint with the following parameters:
* grant_type REQUIRED. The value MUST be set to
urn:ietf:params:oauth:grant-type:token-exchange.
* audience REQUIRED. The value MUST be set to the Trust Domain
name.
* scope REQUIRED. A space-delimited list of case-sensitive strings
where the value(s) MUST represent the specific purpose or intent
of the transaction.
* requested_token_type REQUIRED. The value MUST be
urn:ietf:params:oauth:token-type:txn_token.
* subject_token REQUIRED. The value MUST contain a token that
represent the subject of the transaction. The manner in which the
subject is represented in the subject_token depends on the
subject_token_type. The subject_token MAY be:
- An inbound token received by an external endpoint (e.g. an API
Gateway).
Tulshibagwale, et al. Expires 31 January 2027 [Page 15]
Internet-Draft Txn-Tokens July 2026
- A self-signed JWT constructed by a workload initiating a
transaction.
- An unsigned JSON object constructed by a workload initiating a
transaction.
- Any other format that is understood by the TTS.
The type of the subject_token field is identified by
subject_token_type.
* subject_token_type REQUIRED. The value MUST indicate the type of
the token or value present in the subject_token parameter.
The following additional parameters are defined for the Txn-Token
Request:
* request_context RECOMMENDED. This parameter contains a JSON
object which represents the context of this transaction.
* request_details RECOMMENDED. This parameter contains a JSON
object which contains additional details about the request. This
could include API parameters, authorization criteria or other
details the requester would like to pass to the TTS. The TTS uses
this data along with other information at its disposal to
construct the tctx JSON object (if required).
All parameters are encoded using the "application/x-www-form-
urlencoded" format per Appendix B of [RFC6749].
The figure below Figure 5 shows a non-normative example of a Txn-
Token Request. Line breaks added for readability.
POST /txn-token-service/token_endpoint HTTP/1.1
Host: txn-token-service.trust-domain.example
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Atxn_token
&audience=trust-domain.example
&scope=trade.stocks
&subject_token=eyJhbGciOiJFUzI1NiIsImtpZC...kdXjwhw
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
&request_context=%7B%0A%20%20%20%20%20%20%22req_ip%22%3A%20%2269.151.72.123%22%2C%20%0A%20%20%20%20%20%20%22authn%22%3A%20%22face%22%0A%7D
&request_details=%7B%0A%20%20%20%20%20%20%22action%22%3A%20%22BUY%22%2C%0A%20%20%20%20%20%20%22ticker%22%3A%20%22MSFT%22%2C%0A%20%20%20%20%20%20%22quantity%22%3A%20%22100%22%0A%7D
Figure 5: Example: Txn-Token Request
Tulshibagwale, et al. Expires 31 January 2027 [Page 16]
Internet-Draft Txn-Tokens July 2026
11.2. Subject Token Types
The subject_token_type parameter value MUST be a URI [RFC3986]. It
MAY be:
* Any one of the subject token types described in Section 3 of OAuth
2.0 Token Exchange [RFC8693] except the Refresh Token type (i.e.,
urn:ietf:params:oauth:token-type:refresh_token).
* A URN type name when the subject token is a self-signed JWT, as
described below.
* A URN type name when the subject token is an unsigned JSON object,
as described below.
* A custom URN agreed to between requesters and the TTS. The TTS
MAY support other token formats, which MAY be specified in the
subject_token_type parameter.
11.2.1. Self-Signed Subject Token Type
A requester MAY use a self-signed JWT as a subject_token value. In
that case, the requester MUST set the subject_token_type value to:
urn:ietf:params:oauth:token-type:self_signed. This self-signed JWT
MUST contain the following claims:
* iss: The unique identifier of the requesting workload.
* sub: The subject for whom the Txn-Token is being requested. The
TTS SHALL use this value in determining the sub value in the Txn-
Token issued in the response to this request.
* aud: The unique identifier of the TTS. The TTS SHALL verify that
this value matches its own unique identifier.
* iat: The time at which the self-signed JWT was created. Note that
the TTS may reject self-signed tokens with an iat value that is
unreasonably far in the past or future.
* exp: The expiration time for the JWT. Section 6 provides guidance
on setting the expiry of a Txn-Token.
The self-signed JWT MAY contain other claims.
Tulshibagwale, et al. Expires 31 January 2027 [Page 17]
Internet-Draft Txn-Tokens July 2026
11.2.2. Unsigned JSON Object Subject Token Type
A requester MAY use an unsigned JSON object as a subject_token value.
In that case, the requester MUST set the subject_token_type value to:
urn:ietf:params:oauth:token-type:unsigned_json. The JSON object in
the subject token MUST contain the following fields:
* sub: The subject for whom the Txn-Token is being requested. The
TTS SHALL use this value in determining the sub value in the Txn-
Token issued in the response to this request.
The unsigned JSON object MAY contain other fields, and the TTS MAY
consider them when generating the Txn-Token.
11.3. Txn-Token Request Processing
When the TTS receives a Txn-Token Request it:
* MUST validate the requesting workload client authentication and
determine if that workload is authorized to obtain the Txn-Tokens
with the requested value(s) (see Section 13.10). The
authorization policy for determining such issuance is out of scope
for this specification.
* The TTS MUST validate the subject_token, including verifying the
signature, if it is signed.
* The TTS determines the value to specify as the sub of the Txn-
Token and MUST ensure the sub value is unique within the Trust
Domain defined by the aud claim.
* The TTS MUST set the iat claim to the time of issuance of the Txn-
Token.
* The TTS MUST set the aud claim to an identifier representing the
Trust Domain of the TTS. If the TTS supports multiple Trust
Domains, then it MUST determine the correct aud value for this
request.
* The TTS MUST set the exp claim to the expiry time of the Txn-
Token. The TTS MAY consider any exp value present in the
subject_token parameter of the Txn-Token Request in determining
the exp value of the resulting Txn-Token.
* The TTS MUST set the txn claim to a unique ID specific to this
transaction.
Tulshibagwale, et al. Expires 31 January 2027 [Page 18]
Internet-Draft Txn-Tokens July 2026
* The TTS MAY set the iss claim of the Txn-Token to a value defining
the entity that signed the Txn-Token.
* The TTS MUST evaluate the value specified in the scope parameter
of the request to determine the scope claim of the issued Txn-
Token.
* If a request_context parameter is present in the Txn-Token
Request, the TTS SHOULD evaluate the content of the
request_context parameter and may include claims in the rctx claim
of the issued Txn-Token based on the request_context parameter.
The TTS is authoritative for the set of claims made available in
the rctx claim. The claims included in the rctx claim of the
issued Txn-Token may be an exact match of those on the
request_context, may be derived from the request_context, or
independently asserted by the TTS.
* If a request_details parameter is present in the Txn-Token
Request, the TTS SHOULD evaluate the content of the
request_details parameter and may include claims in the tctx claim
of the issued Txn-token based on the request_details parameter.
The claims included in the tctx claim of the issued Txn-Token may
be an exact match of those on the request_details, or may be
derived from the request_details. The TTS is authoritative for
the set of claims made available in the tctx claim and MAY include
additional claims unrelated to the request_details.
The TTS MAY provide additional processing and verification that is
outside the scope of this specification.
11.4. Txn-Token Response
A successful response to a Txn-Token Request MUST include the
following values defined in [RFC8693]:
* The token_type value MUST be set to N_A per guidance in OAuth 2.0
Token Exchange [RFC8693].
* The access_token value MUST be the Txn-Token JWT.
* The issued_token_type value MUST bet set to
urn:ietf:params:oauth:token-type:txn_token.
The Txn-Token Response MUST NOT include the refresh_token value.
If the TTS responds with an error, the error response is as described
in Section 5.2 of [RFC6749].
Tulshibagwale, et al. Expires 31 January 2027 [Page 19]
Internet-Draft Txn-Tokens July 2026
Figure 6 shows a non-normative example of a Txn-Token Response.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"token_type": "N_A",
"issued_token_type": "urn:ietf:params:oauth:token-type:txn_token",
"access_token": "eyJCI6IjllciJ9...Qedw6rx"
}
Figure 6: Example: Txn-Token Response
11.5. Mutual Authentication of the Txn-Token Request
A TTS and requesting workload MUST authenticate each other (mutual
authentication). Workloads MUST authenticate the TTS to ensure that
they do not disclose sensitive information, such as OAuth access
tokens, to a rogue TTS. A TTS MUST authenticate a workload to ensure
the workload is authorized to request a transaction token.
Workloads SHOULD use the https scheme to secure the communication
channel and authenticate the TTS. When using https, TLS certificates
MUST be checked according to Section 4.3.4 of [RFC9110]. At the time
of this writing, TLS version 1.3 [RFC8446] is the most recent
version.
Workloads SHOULD authenticate to a Transaction Token Server using
asymmetric (public-key based) methods or signed client authentication
JWTs in accordance with [RFC7523], which MAY be provisioned using
mechanisms such as [SPIFFE] or other provisioning protocols.
Examples of public-key based authentication include those defined in
OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound
Access Tokens [RFC8705], Workload Authentication Using Mutual TLS
[I-D.ietf-wimse-mutual-tls], WIMSE Workload-to-Workload
Authentication with HTTP Signatures [I-D.ietf-wimse-http-signature]
and WIMSE Workload Proof Token [I-D.ietf-wimse-wpt].
12. Using Txn-Tokens
Txn-Tokens need to be communicated between workloads that depend upon
them to authorize the request. Such workloads will often present
HTTP [RFC9110] interfaces for being invoked by other workloads. This
section specifies the HTTP header the invoking workload MUST use to
communicate the Txn-Token to the invoked workload, when the invoked
workload presents an HTTP interface. Note that the standard HTTP
Tulshibagwale, et al. Expires 31 January 2027 [Page 20]
Internet-Draft Txn-Tokens July 2026
Authorization header MUST NOT be used because that may be used by the
workloads for other purposes.
12.1. "Txn-Token" HTTP Header
A workload that invokes another workload using HTTP and needs to
present a Txn-Token to the invoked workload MUST use the HTTP Header
"Txn-Token" to communicate the Txn-Token in the HTTP Request. The
value of this header MUST be exactly one Txn-Token.
12.2. Txn-Token Validation
A workload that receives a Txn-Token MUST evaluate the token for
validity before authorizing it for activities supported by the
workload. To validate the Txn-Token, the workload MUST:
* Validate the Txn-Token JWS signature.
* Verify the aud claim identifies the Trust Domain of the workload.
* Verify the Txn-Token is not expired.
In addition, any outbound calls made by this workload MUST include
the Txn-Token as it was received so that it is passed unmodified to
any downstream workloads.
Once the Txn-Token is determined to be valid, the workload MAY use
any of the data contained in the Txn-Token to determine if the Txn-
Token authorizes the requested activity. How the workload determines
this authorization is out of scope for this specification.
13. Security Considerations
13.1. Txn-Token Replay Risks
A Txn-Token is not resistant to replay attacks. A long-lived Txn-
Token therefore represents a risk if it is discovered by an attacker
(e.g. if it is stored in a file), and then replayed. For this
reason, a Txn-Token lifetime MUST be kept short and follow the
guidance given in Section 6.
The use of a unique transaction identifier (txn claim) allows for
discovery of Txn-Token replay as described in Section 13.2.
Tulshibagwale, et al. Expires 31 January 2027 [Page 21]
Internet-Draft Txn-Tokens July 2026
13.2. Unique Transaction Identifier
A Txn-Token conveys user identity and authorization context across
workloads in a Call Chain. The txn claim is a unique identifier
that, when logged by the TTS and workloads, enables discovery and
auditing of successful and failed transactions. The txn value SHOULD
be unique within the Trust Domain.
A workload receiving a Txn-Token can store the txn value of each Txn-
Token for the time window in which the Txn-Token would be accepted to
prevent multiple uses of the same Txn-Token. Requests to the same
workload for which the txn value has been seen before would be
declined. When strictly enforced, such a single-use check provides a
very strong protection against Txn-Token replay, but it may not
always be feasible in practice, e.g., when multiple instances of the
same workload receiving a Txn-Token have no shared state.
13.3. Refresh Tokens
OAuth refresh tokens are used to obtain access tokens as defined in
[RFC6749] and MUST NOT be used to request transaction tokens (see
Section 11.2. Since Txn-Tokens are short-lived (Section 6), the Txn-
Token response from the TTS MUST NOT include a refresh token (see
Section 11.4).
13.4. Access Tokens
When creating Txn-Tokens, the Txn-Token MUST NOT contain the access
token presented to the external endpoint. If an access token is
included in a Txn-Token, an attacker may extract the access token
from the Txn-Token, and replay it to any Resource Server that can
accept that access token. Txn-Token expiry does not protect against
this attack since the access token may remain valid even after the
Txn-Token has expired.
Access tokens are typically short-lived but they can be invalidated
before their expiration due to security or policy changes. In
addition to standard access token validation, a TTS MAY, based on the
risk profile of the deployment or transaction, verify whether the
presented access token was invalidated. Where appropriate,
implementations can use OAuth 2.0 Token Introspection [RFC7662] or
similar mechanisms to obtain up-to-date token status from the
authorization server.
Tulshibagwale, et al. Expires 31 January 2027 [Page 22]
Internet-Draft Txn-Tokens July 2026
13.5. Subject Token Types
Identifies the token type of the subject_token which is generally a
token the requesting workload received (e.g. an OAuth token or a SAML
assertion). In the absence of an appropriate incoming token, the
requesting service MAY use a self-signed JWT, an unsigned JSON object
or any other format to represent the details of the requester and the
transaction to the TTS.
13.6. Scope Processing
The authorization model within a Trust Domain boundary may be quite
different from the authorization model (e.g. OAuth scopes) used with
clients external to the Trust Domain. This makes managing
unintentional scope increase a critical aspect of the TTS. The TTS
MUST ensure that the requested scope of the Txn-Token is equal or
less than the scope(s) associated with the original subject_token.
13.7. TTS Discovery
A workload may use various mechanisms to determine the correct
instance of a TTS with which to interact. Workloads MUST retrieve
configuration information from a trusted source to minimize the risk
of a threat actor providing malicious configuration data that points
to an instance of a TTS under it's control which could be used to
collect access tokens sent as part of the Transaction Token Request
message.
To mitigate this risk, workloads SHOULD authenticate the service
providing the configuration information and verify the integrity of
the configuration information. This ensures that no unauthorized
entity can insert or alter configuration data. The workload SHOULD
use Transport Layer Security (TLS) to authenticate the endpoint and
secure the communication channel. Additionally, application-layer
signatures or message authentication codes MAY be used to detect any
tampering with the configuration information.
13.8. Workload Configuration Protection
A deployment may include multiple instances of a TTS to improve
resiliency, reduce latency and enhance scalability. A workload may
be configured to access more than one instance of a TTS to ensure
reliability or reduce latency for transaction token requests. The
workload configuration should be protected against unauthorized
addition or removal of TTS instances. An attacker may perform a
denial of service attack or degrade the performance of a system by
removing an instance of a TTS from the workload configuration.
Tulshibagwale, et al. Expires 31 January 2027 [Page 23]
Internet-Draft Txn-Tokens July 2026
13.9. TTS Authentication
A workload may accidently send a transaction token request to a
service that is not a TTS, or an attacker may attempt to impersonate
a TTS in order to gain access to transaction token requests which
includes sensitive information like access tokens. To minimise the
risk of leaking sensitive information like access tokens that are
included in the transaction token request, the workload MUST ensure
that it authenticates the TTS and only contacts instances of the TTS
that is authorized to issue transaction tokens.
13.10. TTS Issuance Policies
A TTS should be selective in which workloads can successfully request
a Txn-Token. A TTS does not need to issue a Txn-Token to every
workload that requests one. TTS token issuance decisions, including
whether to issue a Txn-Token and the claims it contains, are
typically subject to deployment-specific issuance policies and
business logic. For example, an API gateway handling a user-
initiated request might be permitted to obtain a Txn-Token carrying
request context such as a transaction amount, while a downstream
service in the same Call Chain might not. Such policies may vary
based on system architecture, workload identity, transaction context,
or risk, and may result in different Txn-Token contents or denial of
issuance. The definition and management of these policies are
deployment-specific and out of scope for this specification.
13.11. TTS Key Rotation
The TTS may need to rotate signing keys. When doing so, it MAY adopt
the key rotation practices in Section 10.1.1 of [OpenIdConnect].
13.12. Transaction Tokens Are Not Authentication Credentials
A workload MUST NOT use a transaction token to authenticate itself to
another workload, service or the TTS. Transaction tokens represents
information relevant to authorization decisions and are not workload
identity credentials. Authentication between the workload and the
TTS is described in Section 11.5.
13.13. Transaction Tokens Are Not OAuth 2.0 Access Tokens
A workload MUST NOT use a transaction token as an OAuth 2.0 Access
Token. An OAuth 2.0 Access Token represents a grant of authority to
a client, a transaction token represents the context of a specific
transaction. The separation of the transaction token from the OAuth
2.0 Access Token is a deliberate design choice as described in
Section 1.
Tulshibagwale, et al. Expires 31 January 2027 [Page 24]
Internet-Draft Txn-Tokens July 2026
Transaction tokens support the principle of least privilege since
they are narrowly scoped to a single transaction and have short
lifetimes. This makes them less susceptible to broad replay attacks
than the longer-lived access tokens. By maintaining a distinct token
type, the protocol ensures that context propagation while minimizing
the risk of lateral access if a transaction token is intercepted
within the Trust Domain. This separation also reduces the need for
including transaction context in the access token, reducing token
size.
Using a dedicated HTTP header from the Authorization: Bearer header
for transaction tokens allows services to distinguish between an
access token, which carries authorization delegation information, and
the transaction token, which carries transaction context.
13.14. Unknown subject_token scope
If the scope associated with a subject_token cannot be determined
from the token or another trusted source, the TTS cannot ensure that
the requested scope does not expand the authorization represented by
that token. The TTS MUST reject the Txn-Token Request and MUST NOT
treat an unknown scope as unconstrained.
13.15. Txn-Token as a subject_token
A TTS MUST exercise caution when receiving a Txn-token as a
subject_token. Any Txn-Token issued in response to such a request is
effectively a replacement Txn-Token. Replacing Txn-Tokens
potentially negates the primary purpose of having Txn-Tokens. When
issuing replacement Txn-Tokens, a TTS:
* MAY enable modifications to asserted values that reduce the scope
of permitted actions.
* MAY enable additional asserted values.
* MUST NOT enable modification to asserted values that expand the
scope of permitted actions.
* MUST NOT modify txn, sub, and aud values of the Txn-Token in the
request.
* MUST NOT issue a new Txn-Token when the Txn-Token being replaced
has expired.
* MAY issue a replacement Txn-Token with a lifetime exceeding the
lifetime of the input Txn-Token, subject to the policy of the TTS.
Tulshibagwale, et al. Expires 31 January 2027 [Page 25]
Internet-Draft Txn-Tokens July 2026
* SHOULD limit the number of times a Txn-Token is replaced if it
allows extending the lifetime beyond that of the input Txn-Token
to reduce replay risks.
* MUST maintain the Call Chain of workloads that requested the Txn-
Token being replaced in the subsequently issued Txn-Token. The
mechanism for maintaining this Call Chain is out of scope for this
specification.
13.16. Determining signing keys
The iss claim may be used to identify the signer of the Txn-Token in
cases where the signing keys are not predetermined.
14. Preserving transaction context across Trust Domains
Txn-Tokens are only valid within the Trust Domain identified by the
aud claim as defined in Section 9.2. When a workload needs to access
a resource in a different Trust Domain to complete a transaction, and
the identity and authorization context from the Txn-Token needs to be
preserved, it SHOULD use OAuth Identity and Authorization Chaining
Across Domains [I-D.ietf-oauth-identity-chaining].
15. Privacy Considerations
15.1. Handling of Personal Information
Claims contained within transaction tokens may be considered personal
information (PI) or personally identifying information (PII) in some
jurisdictions and if so their values should be protected accordingly.
For example, requester IP address (req_ip) is often considered
personal information and therefore must be handled according to
jurisdictional requirements.
15.2. Logging
Complete Txn-Tokens MUST NOT be logged verbatim. This is in order to
prevent replay of tokens or leakage of PII or other sensitive
information via log files. A hash of the Txn-Token may be logged to
allow for correlation with the log files of the TTS that records
issued tokens. Alternatively the JWS payload of a Txn-Token may be
logged after the signature has been removed. If the Txn-Token
contains PII, then care should be taken in logging the content of the
Txn-Token so that the PII does not get logged.
Tulshibagwale, et al. Expires 31 January 2027 [Page 26]
Internet-Draft Txn-Tokens July 2026
16. IANA Considerations
This specification registers the following token type identifiers to
the "OAuth URI" subregistry of the "OAuth Parameters"
[IANA.OAuth.Parameters] registry. It also registers the following
claims defined in Section Section 9.2 in the IANA JSON Web Token
Claims Registry defined in [RFC7519]. It also registers the Media
Type [IANA.MediaTypes] "txntoken+jwt" as defined in the section
Section 9.1.
16.1. OAuth URI Subregistry Contents
* URN: urn:ietf:params:oauth:token-type:txn_token
- Common Name: Transaction Token
- Change Controller: IETF
- Specification Document Section Section 11.1 of this
specification
* URN: urn:ietf:params:oauth:token-type:self_signed
- Common Name: Token type for Self-signed JWT
- Change Controller: IETF
- Specification Document: Section Section 11.2.1 of this
specification
* URN: urn:ietf:params:oauth:token-type:unsigned_json
- Common Name: Token type for Unsigned JSON Object
- Change Controller: IETF
- Specification Document: Section Section 11.2.2 of this
specification
16.2. JWT Claims Registry Contents
* Claim Name: tctx
- Claim Description: The transaction authorization details
- Change Controller: IETF
Tulshibagwale, et al. Expires 31 January 2027 [Page 27]
Internet-Draft Txn-Tokens July 2026
- Specification Document: Section Section 9.2 of this
specification
* Claim Name: rctx
- Claim Description: The requester context
- Change Controller: IETF
- Specification Document: Section Section 9.2 of this
specification
16.3. IANA Media Type Registration Contents
The following entry will be proposed using the IANA Media Type
registration [IANA.MediaTypes] form.
* Type Name: application
* Subtype Name: txntoken+jwt
* Change Controller: IETF
* Required Parameters: N/A.
* Optional Parameters: N/A.
* Encoding Considerations: 7-bit text
* Security Considerations:
1. The media type is used to identify JWTs that may be used as
Transaction Tokens. It is a piece of data, and may not
contain executable content.
2. Transaction Tokens are short-lived tokens used within a
trusted environment, so there are no privacy considerations.
Transaction Tokens are unmodifiable tokens, which need
integrity protection.
3. The JWTs representing Transaction Tokens are signed, and
therefore are integrity protected. A recipient of a
Transaction Token must verify the signature on the Transaction
Token before using it.
4. There are no additional security considerations specific to
the use of JWTs as Transaction Tokens.
Tulshibagwale, et al. Expires 31 January 2027 [Page 28]
Internet-Draft Txn-Tokens July 2026
5. The Transaction Tokens format does not require the use of
links within the token. If links are used by specific
instances of Transaction Tokens, then their interpretation is
usage specific.
* Interoperability Considerations: Transaction Tokens inherit all
interoperability properties of JWTs.
* Published Specification: this document (when published).
* Application Usage: Any application supporting the use of JWTs.
* Fragment Identifier Consideration: N/A.
* Restrictions on Usage: Any application supporting the use of JWTs.
* Intended Usage: Common
* Contact Person: Atul Tulshibagwale
16.4. HTTP Header
The header name Txn-Token is proposed to be added to the HTTP Field
Name Registry [IANA.HTTP.FieldNames] as an unstructured Header Field.
This header is defined in the section Section 12.1. The following
entry will be proposed in the HTTP Field Name Registry. Note that
this is an unstructured field, therefore the value of the Type field
is left empty as shown below:
* Field Name: Txn-Token
* Type:
* Status: permanent
* Specification Document: Section Section 12.1 of this document
* Comment: The Authorization header cannot be used for Txn-tokens
because that header may be used for service-to-service
authorization, and the services may simultaneously require the use
of Txn-tokens to convey detailed immutable information such as
user identity and details of fine-grained authorization that are
included in the Txn-token.
17. References
17.1. Normative References
Tulshibagwale, et al. Expires 31 January 2027 [Page 29]
Internet-Draft Txn-Tokens July 2026
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/rfc/rfc3986>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/rfc/rfc8446>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/rfc/rfc6749>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/rfc/rfc7519>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/rfc/rfc7515>.
[RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token
(JWT) Profile for OAuth 2.0 Client Authentication and
Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May
2015, <https://www.rfc-editor.org/rfc/rfc7523>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/rfc/rfc7662>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J.,
and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693,
DOI 10.17487/RFC8693, January 2020,
<https://www.rfc-editor.org/rfc/rfc8693>.
[RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
"Security Event Token (SET)", RFC 8417,
DOI 10.17487/RFC8417, July 2018,
<https://www.rfc-editor.org/rfc/rfc8417>.
Tulshibagwale, et al. Expires 31 January 2027 [Page 30]
Internet-Draft Txn-Tokens July 2026
[RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T.
Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication
and Certificate-Bound Access Tokens", RFC 8705,
DOI 10.17487/RFC8705, February 2020,
<https://www.rfc-editor.org/rfc/rfc8705>.
[RFC9068] Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0
Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October
2021, <https://www.rfc-editor.org/rfc/rfc9068>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
[RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/rfc/rfc9111>.
[RFC9651] Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
<https://www.rfc-editor.org/rfc/rfc9651>.
[I-D.ietf-oauth-identity-chaining]
Schwenkschuster, A., Kasselman, P., Burgin, K., Jenkins,
M. J., Campbell, B., and A. Parecki, "OAuth Identity and
Authorization Chaining Across Domains", Work in Progress,
Internet-Draft, draft-ietf-oauth-identity-chaining-17, 19
July 2026, <https://datatracker.ietf.org/doc/html/draft-
ietf-oauth-identity-chaining-17>.
[IANA.HTTP.FieldNames]
"HTTP Authentication Schemes", n.d.,
<https://www.iana.org/assignments/http-fields/>.
[IANA.OAuth.Parameters]
IANA, "OAuth Parameters", n.d.,
<https://www.iana.org/assignments/oauth-parameters>.
[IANA.MediaTypes]
IANA, "Media Types", n.d.,
<http://www.iana.org/assignments/media-types>.
Tulshibagwale, et al. Expires 31 January 2027 [Page 31]
Internet-Draft Txn-Tokens July 2026
[OpenIdConnect]
Sakimura, N., Bradley, J., Jones, M., Medeiros, B. de.,
and C. Mortimore, "OpenID Connect Core 1.0 incorporating
errata set 2", November 2014,
<https://openid.net/specs/openid-connect-core-1_0.html>.
17.2. Informative References
[RFC8176] Jones, M., Hunt, P., and A. Nadalin, "Authentication
Method Reference Values", RFC 8176, DOI 10.17487/RFC8176,
June 2017, <https://www.rfc-editor.org/rfc/rfc8176>.
[SPIFFE] Cloud Native Computing Foundation, "Secure Production
Identity Framework for Everyone", n.d.,
<https://spiffe.io/docs/latest/spiffe-about/overview/>.
[I-D.ietf-wimse-arch]
Salowey, J. A., Rosomakho, Y., and H. Tschofenig,
"Workload Identity in a Multi System Environment (WIMSE)
Architecture", Work in Progress, Internet-Draft, draft-
ietf-wimse-arch-08, 6 July 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-wimse-
arch-08>.
[I-D.ietf-wimse-mutual-tls]
Salowey, J. A. and Y. Rosomakho, "Workload Authentication
Using Mutual TLS", Work in Progress, Internet-Draft,
draft-ietf-wimse-mutual-tls-02, 6 July 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-wimse-
mutual-tls-02>.
[I-D.ietf-wimse-http-signature]
Salowey, J. A. and Y. Sheffer, "WIMSE Workload-to-Workload
Authentication with HTTP Signatures", Work in Progress,
Internet-Draft, draft-ietf-wimse-http-signature-05, 20
July 2026, <https://datatracker.ietf.org/doc/html/draft-
ietf-wimse-http-signature-05>.
[I-D.ietf-wimse-wpt]
Campbell, B. and A. Schwenkschuster, "WIMSE Workload Proof
Token", Work in Progress, Internet-Draft, draft-ietf-
wimse-wpt-01, 2 March 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-wimse-
wpt-01>.
Tulshibagwale, et al. Expires 31 January 2027 [Page 32]
Internet-Draft Txn-Tokens July 2026
Acknowledgements
The authors would like to thank John Bradley, Kelley Burgin, Brian
Campbell, Naveen CM, Andrii Deinega, Apoorva Deshpande, Daniel Fett,
Evan Gilman, Joseph Heenan, Watson Ladd, Kai Lehmann, Jeff Lombardo,
Dan Moore, Steinar Noem, Ashay Raut, Justin Richer, Joe Salowey, Dean
Saxe, Arndt Schwenkschuster, Dag Sneeggen, Yaron Scheffer, Orie
Steele, Dmitry Telegin, and Hannes Tschofenig for supporting,
commenting, contributing and providing feedback on this
specification.
Document History
[[ To be removed from final specification ]]
Since Draft 10
* Fixed typo in document history
Since Draft 09
* Editorial text describing claims
Since Draft 08
* Added document history for changes from 07 to 08
* Added TTS Issuance Guidance policies (see issue
https://github.com/oauth-wg/oauth-transaction-tokens/issues/321)
* Provide guidance on cross-domain access (see https://github.com/
oauth-wg/oauth-transaction-tokens/issues/326)
* Added security consideration for invalidated tokens (see issue
https://github.com/oauth-wg/oauth-transaction-tokens/issues/321)
* Added doublequotes around the "Txn-Token" header name to
distinguish it from the usage of Txn-Token as a name for
Transaction Tokens.
* Added Brian Campbell as a contributor.
* Renamed Requester-Context section to Request Context and removed
specification of rctx specific claims (see issue
https://github.com/oauth-wg/oauth-transaction-tokens/issues/323)
Tulshibagwale, et al. Expires 31 January 2027 [Page 33]
Internet-Draft Txn-Tokens July 2026
* Clarified how multiple workloads are represented in the req_wl
claim (see issue https://github.com/oauth-wg/oauth-transaction-
tokens/issues/331)
* Clarify transaction tokens vs OAuth 2.0 access tokens
* Merged Overview and Introduction sections (see https://github.com/
oauth-wg/oauth-transaction-tokens/issues/327)
* Changed additionally defined request parameters from OPTIONAL to
RECOMMENDED see https://github.com/oauth-wg/oauth-transaction-
tokens/issues/332)
* Consistent cappitalisation of trust domain and call chain (see
https://github.com/oauth-wg/oauth-transaction-tokens/issues)
* Updated JWT body claims from OPTIONAL to RECOMMENDED (see
https://github.com/oauth-wg/oauth-transaction-tokens/issues/330)
* Clarified TTS behaviour wrt txtx and rctx, fixed examples (see
https://github.com/oauth-wg/oauth-transaction-tokens/issues/349)
Since Draft 07
* Fixed author affiliation (https://github.com/oauth-wg/oauth-
transaction-tokens/pull/318)
* Added details to the benefits section (https://github.com/oauth-
wg/oauth-transaction-tokens/pull/316)
* Updated the definition of the req_wl claim (https://github.com/
oauth-wg/oauth-transaction-tokens/pull/315)
* Editorial changes for grammar and clarity (https://github.com/
oauth-wg/oauth-transaction-tokens/pull/307, https://github.com/
oauth-wg/oauth-transaction-tokens/pull/308)
* Standardized terminology throughout the document
(https://github.com/oauth-wg/oauth-transaction-tokens/pull/304)
* Revised handling of personal information in Privacy section
(hhttps://github.com/oauth-wg/oauth-transaction-tokens/pull/306/)
* Clarified token replay risks (https://github.com/oauth-wg/oauth-
transaction-tokens/pull/305)
* Fixed section numbering issue (https://github.com/oauth-wg/oauth-
transaction-tokens/issues/352)
Tulshibagwale, et al. Expires 31 January 2027 [Page 34]
Internet-Draft Txn-Tokens July 2026
* Made iss optional in all circumstances, and added Seurity
Consideration that provides guideance on using it when signing
keys are not predetmined.
Since Draft 06
* Remove contradiction in "request_details" description and simplify
normative langugage Clarify claim usage (https://github.com/oauth-
wg/oauth-transaction-tokens/issues/228).
* Consistency in terms of expectations of input token
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/224)
* Replace StringOrURI with string Replace StringOrURI with String
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/195)
* Include token theft as a threat to be mitigated Consider
information disclosure as a benefit (https://github.com/oauth-wg/
oauth-transaction-tokens/issues/207)
* Remove definition of Authorization Context Be more specific on
Authorization Context (https://github.com/oauth-wg/oauth-
transaction-tokens/issues/192)
* Clarify text on use of empty parameter: https://github.com/oauth-
wg/oauth-transaction-tokens/issues/235
* Clarify that workloads should ensure it is communicating with a
legitimate instance of a transaction token service
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/233)
* Clarify need to validate signature on subject_token if it is
signed.
* Clarify role of transaction tokens in call chain
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/203)
* Revise normative langugage for enforcement of token expiry
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/210)
* Remove exp field from unsigned token (https://github.com/oauth-wg/
oauth-transaction-tokens/issues/201)
* Change document category from informational to standards track
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/169)
* Clarify that txnshould remain unchanged when included in a
replacement transaction token.
Tulshibagwale, et al. Expires 31 January 2027 [Page 35]
Internet-Draft Txn-Tokens July 2026
* Editorial updates (https://github.com/oauth-wg/oauth-transaction-
tokens/issues/204)
* Removed the requirement to encode parameters in based64url format
* Rename the purpose claim to scope
* Enhanced the description of the sub claim addressing issue #225
* Removed references to replacing transaction tokens, and added a
note in the Security Considerations to clarify replacement
concerns.
* Editorial updates identified by Dan Moore (https://github.com/
oauth-wg/oauth-transaction-tokens/issues/236)
* Editorial comments from Joe Saloway (https://github.com/oauth-wg/
oauth-transaction-tokens/issues/219)
* Clarify request_details (https://github.com/oauth-wg/oauth-
transaction-tokens/issues/197)
* Add normative language for processing Txn-Tokens
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/270)
* Strengthen normative language for Txn-Token Requests
(https://github.com/oauth-wg/oauth-transaction-tokens/issues/209)
* Aligned with WIMSE terminology (https://github.com/oauth-wg/oauth-
transaction-tokens/issues/213)
* Updated Acknowledgement section (https://github.com/oauth-wg/
oauth-transaction-tokens/issues/260)
* Rewrote the 'Handling of Personal Information' section of Privacy
Considerations (https://github.com/oauth-wg/oauth-transaction-
tokens/issues/290)
* Removed text related to replacement transaction tokens
* Updated references to call chain to be capitalized and fixed some
definitions (https://github.com/oauth-wg/oauth-transaction-tokens/
issues/284)
* Update definition of req_wl claim (https://github.com/oauth-wg/
oauth-transaction-tokens/issues/311)
Tulshibagwale, et al. Expires 31 January 2027 [Page 36]
Internet-Draft Txn-Tokens July 2026
Since Draft 05
* Strengthened prohibition on expanding TraT scope
(https://github.com/oauth-wg/oauth-transaction-tokens/pull/173)
* Clarified that TraTs can exceed request token lifetime, but cannot
use expired tokens in request (https://github.com/oauth-wg/oauth-
transaction-tokens/pull/170)
* Improved abstract for clarity (https://github.com/oauth-wg/oauth-
transaction-tokens/pull/160)
* Clarified that the HTTP header Txn-Token is unstructured
(https://github.com/oauth-wg/oauth-transaction-tokens/pull/176)
* Scope Processing: behavior undefined when subject_token has no
scope claim (https://github.com/oauth-wg/oauth-transaction-tokens/
issues/357)
Since Draft 04
* Clarified Transaction Token Service discovery (https://github.com/
oauth-wg/oauth-transaction-tokens/pull/153)
* Language improvements (https://github.com/oauth-wg/oauth-
transaction-tokens/pull/148)
* Renamed azd claim to tctx claim (https://github.com/oauth-wg/
oauth-transaction-tokens/pull/150)
* Fixed terminology captialization (https://github.com/oauth-wg/
oauth-transaction-tokens/pull/151)
* Added key rotation guidance (https://github.com/oauth-wg/oauth-
transaction-tokens/pull/156)
* Clarified text around external vs internal invocation
(https://github.com/oauth-wg/oauth-transaction-tokens/pull/157)
Contributors
Brian Campbell
Ping Identity
Email: bcampbell@pingidentity.com
Authors' Addresses
Tulshibagwale, et al. Expires 31 January 2027 [Page 37]
Internet-Draft Txn-Tokens July 2026
Atul Tulshibagwale
CrowdStrike
Email: atul.tulshibagwale@crowdstrike.com
George Fletcher
Practical Identity LLC
Email: george@practicalidentity.com
Pieter Kasselman
Defakto Security
Email: pieter@defakto.security
Tulshibagwale, et al. Expires 31 January 2027 [Page 38]