Transaction Tokens For Agents

3.2.1. Subject-Initiated Flow

When a human subject initiates the workflow, the following steps occur:¶

1. The subject invokes the agent application to perform a task.¶

2. The agent application calls an external endpoint. The external endpoint returns an OAuth challenge.¶

3. The agent application authenticates using an OAuth 2.0 Authorization Code flow [RFC6749] access token. The access token contains sub and client_id claims as per [RFC9068]. If the access token represents a delegated flow (human delegating to agent), it MAY contain an act claim per [RFC8693].¶

4. The external endpoint submits the received access token along with its subject token to the Txn-Token Service. Subject token requirements are specified in OAUTH-TXN-TOKENS.¶

5. The Txn-Token Service validates the access token.¶

6. The Txn-Token Service populates the Txn-Token's sub claim following the rules specified in OAUTH-TXN-TOKENS. The sub claim is determined based on the subject_token provided in the request.¶

7. If the access token contains an act claim, the Txn-Token Service copies the act claim value to the Txn-Token's act field. The value is copied as-is without modification.¶

8. If the TTS has access to an Agent Attribute Store or equivalent mechanism, it performs a lookup using the client_id from the access token. If the client_id resolves to a registered agent, the TTS populates the agentic_ctx claim. This is the case when agent is within trust domain and user start request using agent within trust domain. If no Agent Attribute Store is available, the TTS MAY still populate agentic_ctx using information derivable from the token exchange (e.g., client_id as proximate_agent.id).¶

9. The Txn-Token Service issues the Txn-Token to the requesting workload.¶

+--------+     +-------+     +----------+     +-----+     +----------+
| Human  |     |  3P   |     | External |     | TTS |     |  Agent   |
| Subject|     | Agent |     | Endpoint |     |     |     |Attr Store|
+---+----+     +---+---+     +----+-----+     +--+--+     +----+-----+
    |              |               |              |              |
    | 1. Invoke    |               |              |              |
    |  task        |               |              |              |
    |------------->|               |              |              |
    |              |               |              |              |
    |              | 2. Call with   |              |              |
    |              |  access_token |              |              |
    |              |  (sub, act)   |              |              |
    |              |-------------->|              |              |
    |              |               |              |              |
    |              |               | 4. Request   |              |
    |              |               |  Txn-Token   |              |
    |              |               |  (access_token + subject_token)
    |              |               |------------->|              |
    |              |               |              |              |
    |              |               |              | 8. Lookup    |
    |              |               |              |  client_id   |
    |              |               |              |............->|
    |              |               |              |              |
    |              |               |              |  agent=true  |
    |              |               |              |<.............|
    |              |               |              |              |
    |              |               |              | 9. Issue     |
    |              |               |              |  Txn-Token:  |
    |              |               |              |  sub=user    |
    |              |               |              |  act={agent} |
    |              |               |              |  agentic_ctx |
    |              |               |              |              |
    |              |               |<-------------|              |
    |              |               |              |              |

Legend:
- `-->` Solid: Primary request/response flow
- `...>` Dotted: Registry lookup (optional, per §3.6)

Note: Steps 3 (OAuth 2.0 Authorization Code Grant), 5 (access token validation), 6 (sub claim population), and 7 (act claim copy) are internal operations not shown in the diagram. Diagram step 2 shows the agent calling the external endpoint with an access token already in hand; the Authorization Code flow that produces that token (text step 3) is omitted for clarity.¶

3.2.2. Autonomous Flow

When the agent application operates autonomously, the following steps occur:¶

1. The agent application initiates a task based on an event or scheduled assignment.¶

2. The agent application calls an external endpoint. The OAuth challenge flow starts.¶

3. The agent application authenticates using an OAuth 2.0 Client Credentials Grant [RFC6749].¶

4. The agent application uses the access token to call the external endpoint.¶

5. The external endpoint submits the received access token along with its subject token to the Txn-Token Service. Subject token requirements are specified in OAUTH-TXN-TOKENS.¶

6. The Txn-Token Service validates the access token.¶

7. The Txn-Token Service populates the Txn-Token's sub claim following the rules specified in OAUTH-TXN-TOKENS. For autonomous agents, the sub claim is determined based on the subject_token provided in the request, which typically represents the agent's own identity.¶

8. If the access token contains an act claim, the Txn-Token Service copies it to the Txn-Token. For Client Credentials Grant flows, the access token typically does not contain an act claim, and therefore the Txn-Token MUST NOT contain an act claim.¶

9. If the TTS has access to an Agent Attribute Store, it performs a lookup and populates agentic_ctx if the caller is identified as an agent. If no Agent Attribute Store is available, the TTS MAY still populate agentic_ctx using information derivable from the token exchange.¶

10. The Txn-Token Service issues the Txn-Token to the requesting workload.¶

+-------+     +----------+     +-----+     +----------+
|  1P   |     | External |     | TTS |     |  Agent   |
| Agent |     | Endpoint |     |     |     |Attr Store|
+---+---+     +----+-----+     +--+--+     +----+-----+
    |               |              |              |
    | 1. Event/     |              |              |
    |  schedule     |              |              |
    |  triggers     |              |              |
    |  task         |              |              |
    |               |              |              |
    | 3. Client     |              |              |
    |  Creds Grant  |              |              |
    |  (get         |              |              |
    |  access_tok)  |              |              |
    |-------------->|              |              |
    |<--------------|              |              |
    |               |              |              |
    | 4. Call with  |              |              |
    |  access_token |              |              |
    |  (no act)     |              |              |
    |-------------->|              |              |
    |               |              |              |
    |               | 5. Request   |              |
    |               |  Txn-Token   |              |
    |               |  (access_token + subject_token)
    |               |------------->|              |
    |               |              |              |
    |               |              | 9. Lookup    |
    |               |              |  client_id   |
    |               |              |............->|
    |               |              |              |
    |               |              |  agent=true  |
    |               |              |<.............|
    |               |              |              |
    |               |              | 10. Issue    |
    |               |              |  Txn-Token:  |
    |               |              |  sub=agent   |
    |               |              |  (no act)    |
    |               |              |  agentic_ctx |
    |               |              |              |
    |               |<-------------|              |
    |               |              |              |

Note: In autonomous flows, `act` is absent (no human delegation).
The `originator.id` in `agentic_ctx` is set from `client_id`.
Steps 2 (OAuth challenge), 6 (token validation), 7 (sub population),
and 8 (act copy) are internal operations not shown in the diagram.
Step 3 shows the OAuth AS interaction simplified to the External Endpoint.

3.3.1. Replacement When Caller is Identified as an Agent

When the workload requesting a replacement Txn-Token is identified as an agent (per Section 3.6), the following rules apply in addition to the base specification replacement rules:¶

• The sub, txn, and aud claims MUST NOT be modified (per base specification).¶

• The act claim, if present, MUST NOT be modified. The act claim is immutable throughout the entire transaction lifetime.¶

• The scope claim can only be attenuated (per base specification).¶

• The req_wl claim MUST be updated by appending the current requesting workload's identifier, using the comma (,) character as separator per the base specification.¶

• The agentic_ctx claim MUST be updated as follows:¶

  • The proximate_agent.id field MUST be set to the identifier of the new requesting agent.¶

  • If proximate_agent.session_id is present, it MUST be updated alongside proximate_agent.id to reflect the session identifier of the new requesting agent.¶

  • The originator.session_id field, if present, MUST NOT be modified.¶

  • The chain_metadata.hop_count MUST be incremented by one.¶

  • If chain_metadata.min_assurance_level is present, it MUST be recalculated. The value MUST be the minimum of the existing min_assurance_level and the new agent's assurance level as recorded in the Agent Attribute Store (monotonic attenuation).¶

3.3.2. Replacement When Caller is Not Identified as an Agent

When the workload requesting a replacement Txn-Token is NOT identified as an agent, the TTS MUST follow the base specification [OAUTH-TXN-TOKENS] replacement rules without modification. The agentic_ctx claim, if present in the incoming Txn-Token, MUST be carried forward without modification. The act claim, if present, MUST NOT be modified. This means, even if agents are anywhere in the call chain, the internal workloads receiving a Txn-Token now gets claims in Txn-Token that inform if one or more agents were involved in the call chain and they can do additional authorization checks.¶

3.3.3. Token State Transitions

       INITIAL ISSUANCE                 REPLACEMENT (hop 2)
       ================                 ===================

+------------------+                    +------------------+
| sub: user        |  --- immutable --> | sub: user        |
| act: {3P}        |  --- immutable --> | act: {3P}        |
| txn: abc-123     |  --- immutable --> | txn: abc-123     |
| aud: trust-dom   |  --- immutable --> | aud: trust-dom   |
| scope: billing   |  --- attenuate -> | scope: billing   |
| req_wl: apigw    |  --- append ----> | req_wl: apigw,1P |
+------------------+                    +------------------+
| agentic_ctx:     |                    | agentic_ctx:     |
|  proximate: 3P   |  --- update ----> |  proximate: 1P   |
|  originator: 3P  |  --- immutable -> |  originator: 3P  |
|  hop_count: 1    |  --- increment -> |  hop_count: 2    |
|  min_assur: (opt)|  --- attenuate -> |  min_assur: (opt)|
+------------------+                    +------------------+

3.5.1. Normative Fields

The following fields within agentic_ctx are defined by this specification:¶

proximate_agent:

REQUIRED. A JSON object identifying the agent whose request caused the current token to be issued or most recently replaced. The object contains the following sub-fields:¶

id:

REQUIRED. A string identifying the proximate agent. At initial issuance, the TTS sets this field to the agent identifier derived from the access token (via act.sub, Agent Attribute Store lookup, or client_id — in that priority order). At each replacement where the requesting workload is identified as an agent, the TTS updates this field to that agent's identifier. When the requesting workload is not identified as an agent, this field MUST NOT be modified. Resource Servers SHOULD use this field when evaluating chain integrity policies and when querying the Agent Attribute Store for richer context about the current agent.¶

session_id:

OPTIONAL. A string identifying the session of the proximate agent as known to that agent's own runtime or infrastructure (e.g., a session identifier assigned by the agent's runtime framework, harness, or SDK). This field is self-asserted by the agent's infrastructure layer and is therefore informational only. Resource Servers and the TTS MUST NOT use this field as an authorization criterion. Its purpose is operational correlation: a workload that observes unexpected behavior may share the txn claim and this value with the proximate agent's owning team, enabling that team to locate the corresponding session in their own runtime logs for debugging or revocation. This field MUST be updated alongside proximate_agent.id during replacement flows so that it always reflects the session of the current proximate agent.¶

originator:

REQUIRED. A JSON object identifying the agent that initiated the transaction chain. The object contains the following sub-fields:¶

id:

REQUIRED. A string identifying the originating agent. This value is set when the initial Txn-Token is issued and MUST NOT be modified during replacement flows. For single-agent flows, originator.id and proximate_agent.id have the same value. The originator.id field exists to support authorization policy evaluation in scenarios where the act claim is absent (e.g., autonomous agent flows using Client Credentials Grant where no delegation occurs). In flows where act is present, the originator.id value will typically match act.sub. This field ensures that the chain origin is always available within agentic_ctx regardless of whether the transaction involves human delegation. Resource Servers SHOULD use this field for authorization policies that depend on the identity of the chain originator, particularly in deployments where the act claim may be absent. Resource Servers MAY also use originator.id to query the Agent Attribute Store for context about the chain origin.¶

session_id:

OPTIONAL. A string identifying the session of the originating agent as known to that agent's own runtime or infrastructure. This value is set at initial token issuance and MUST NOT be modified during replacement flows, mirroring the immutability of originator.id. The trust model and acceptable sources are identical to proximate_agent.session_id: the value is self-asserted and informational only. Resource Servers and the TTS MUST NOT use this field as an authorization criterion. Its purpose is to allow a workload or the TTS to cross-reference the originating agent's runtime logs independently of the proximate agent when investigating a transaction chain.¶

chain_metadata:

REQUIRED. A JSON object containing chain-level integrity metadata. The following sub-fields are defined:¶

hop_count:

REQUIRED. An integer representing the number of agent transitions in the current chain. Set to 1 at initial issuance. Incremented by 1 at each replacement where the caller is identified as an agent. Resource Servers SHOULD evaluate this value against deployment-defined maximum hop limits when making authorization decisions.¶

min_assurance_level:

OPTIONAL. A string representing the minimum assurance level across all agents in the chain. When present, the TTS MUST set this to the minimum of the existing value and the new agent's assurance level during each replacement flow (monotonic attenuation). This field is only meaningful in deployments that define an ordered set of assurance levels and maintain an Agent Attribute Store from which agent assurance levels can be determined. This specification does not define a fixed enumeration of assurance level values. Deployments MUST define their own ordered set and comparison function. Non- normative examples include: "unverified", "low", "medium", "high".¶

attr_store_ref:

OPTIONAL. A URI identifying the Agent Attribute Store endpoint for this trust domain. The TTS MAY include this field to assist Resource Servers in locating the Agent Attribute Store without out-of-band configuration. Resource Servers MAY use this URI to query for richer agent context (posture, provenance, attestation status) using proximate_agent.id or originator.id as the lookup key. This field is informational and does not affect token validity. Resource Servers MUST authenticate the Agent Attribute Store response independently of this field's presence.¶

3.5.2. Agent Attribute Store Queries for Richer Context

Resource Servers that require richer agent context beyond the normative fields — such as operational posture, hardware attestation status, software provenance, or behavioral configuration — SHOULD query the Agent Attribute Store directly using the agent identifier from proximate_agent.id or originator.id.¶

This approach is preferred over embedding deployment-specific attributes in the token for two reasons. First, posture and provenance data are mutable: a token carries a snapshot of state at issuance time, whereas an attribute store query returns current state. Authorization rules based on attribute store-sourced data remain stable across deployment changes, while rules based on token-embedded fields must be updated whenever infrastructure changes. Second, embedding verbose posture fields increases token size without benefit, since the agent identity already provides an unambiguous lookup key.¶

The Agent Attribute Store interface, query protocol, and response format are out of scope for this specification. Deployments MUST ensure that Agent Attribute Store endpoints are authenticated and that store contents are protected with integrity controls appropriate to their security requirements (see Security Considerations).¶

3.5.3. Example agentic_ctx

The following is a non-normative example showing agentic_ctx in a multi-agent flow with all normative fields populated:¶

{
  "agentic_ctx": {
    "proximate_agent": {
      "id": "spiffe://prod.acme.com/billing-agent",
      "session_id": "sess-a3f7c9d2b1e4"
    },
    "originator": {
      "id": "3p-assistant-ext-99",
      "session_id": "sess-7b2e1a9f4c03"
    },
    "chain_metadata": {
      "hop_count": 2,
      "min_assurance_level": "low"
    },
    "attr_store_ref": "https://registry.trust-domain.example/agents"
  }
}

Note: proximate_agent.session_id and originator.session_id are informational only; their values are supplied by the respective agent's infrastructure layer and MUST NOT be used as authorization criteria. Resource Servers requiring posture or provenance data SHOULD query the Agent Attribute Store at attr_store_ref using proximate_agent.id or originator.id as the lookup key.¶

3.5.4. Implementation Guidance

The following guidance applies to implementations using agentic_ctx:¶

• Resource Servers receiving a Txn-Token with agentic_ctx SHOULD evaluate the normative fields (proximate_agent.id, originator.id, chain_metadata) for chain integrity decisions.¶

• Resource Servers requiring richer context SHOULD query the Agent Registry using proximate_agent.id or originator.id. If attr_store_ref is present, it MAY be used to locate the registry endpoint; the response MUST be authenticated independently.¶

• Resource Servers MUST NOT use proximate_agent.session_id or originator.session_id as authorization criteria.¶

• If a Resource Server does not recognize a field within agentic_ctx, it MUST ignore that field and MUST NOT reject the token solely on that basis.¶

3.6.1. Identification Mechanisms

The TTS SHOULD have access to an Agent Attribute Store or equivalent mechanism to identify agent callers. When an Agent Attribute Store is available, the TTS uses it to determine whether agent-specific token issuance rules apply and to source metadata for agentic_ctx population.¶

When the TTS receives a Txn-Token request or replacement request and has access to an Agent Attribute Store, it SHOULD perform the following determination:¶

1. Extract the client_id from the presented access token.¶

2. Query the Agent Attribute Store to determine if the client_id corresponds to a registered agent.¶

3. If the client_id