OAuth Transaction Authorization Challenge

1.1. Human Approval for Agent-Mediated Actions

Software agents, automated workflows, and delegated services can perform operations on behalf of users. Some operations are sufficiently sensitive that a protected resource might require explicit approval before processing them. Examples include sending a payment, publishing content, deleting data, modifying access policy, or disclosing sensitive information.¶

Local confirmation mechanisms within an agent framework can reduce risk, but they are not always visible to the protected resource and do not necessarily produce authorization evidence that the protected resource can validate. A transaction authorization challenge allows the protected resource to require explicit authorization for the concrete operation and to receive a transaction token representing that authorization.¶

1.2. Authorization by a Different Resource Owner

The party that initiated an operation is not always the party authorized to approve it. For example, an agent acting on behalf of one user might request access to a resource owned or controlled by another user. The protected resource can determine that approval from the resource owner, or from another party authorized to act for that resource owner, is required before the operation can proceed.¶

In this case, the transaction authorization challenge allows the protected resource to describe the requested operation and the authorization server to determine the appropriate approving party. The resulting transaction token represents authorization of the challenged operation by the party selected according to authorization server policy.¶

1.3. Organizational Approval

Some operations require approval by an organizational authority rather than by an individual end user. Examples include approving access to regulated data, authorizing a production deployment, granting elevated administrative access, or permitting data transfer to an external party.¶

A transaction authorization challenge allows the protected resource to request authorization evidence from an authorization server or associated policy infrastructure. The authorization server validates the challenge, applies organizational policy, obtains any required approval, and issues a transaction token only when the required authorization has been obtained.¶

4.1. Challenge Capability Signal

An agent indicates that it supports the transaction authorization challenge mechanism by sending the Accept-Txn-Challenge header field with a true value in requests to a protected resource.¶

The Accept-Txn-Challenge header field is an Item Structured Field; see Section 3.3 of [STRUCTURED-FIELDS]. Its value MUST be a Boolean. Any other value type MUST be handled by recipients as if the field were not present. For example, if this field is included multiple times, its type will become a List and the field will be ignored.¶

This document does not define any parameters for the Accept-Txn-Challenge header field value, but future documents might define parameters. Receivers MUST ignore unknown parameters.¶

The following example indicates support for transaction authorization challenges:¶

Accept-Txn-Challenge: ?1

An Accept-Txn-Challenge header field with a false value has the same semantics as when the header field is not present.¶

An agent MUST NOT include the Accept-Txn-Challenge header field unless it has a client interaction path capable of relaying the challenge to a client that can validate the challenge and present it to an authorization server.¶

A protected resource MUST NOT return a transaction authorization challenge unless the request includes an Accept-Txn-Challenge header field with a true value, or the protected resource has out-of-band knowledge that the client supports this specification.¶

4.2. Challenge Response

When a protected resource requires transaction-specific authorization, it returns an HTTP error response indicating that transaction authorization is required. This document defines the OAuth error code transaction_authorization_required for this purpose.¶

For example:¶

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="transaction_authorization_required",
  error_description="Transaction-specific authorization is required",
  transaction_challenge="eyJhbGciOiJFUzI1NiIsInR5cCI6InR4bi1hdXRoei1jaGFsbGVuZ2Urand0..."

The transaction_challenge parameter contains a transaction authorization challenge encoded as a JWS Compact Serialization object as specified in [JWS]. The challenge MUST be signed by the protected resource.¶

The error_description parameter MAY be included to provide a human-readable diagnostic description. The error_description parameter MUST NOT be used as the basis for an authorization decision.¶

A protected resource SHOULD use status code 401 when the request was understood but requires additional transaction-specific authorization. Other status codes MAY be used when appropriate for the application protocol.¶

{
  "iss": "https://resource.example.com",
  "aud": "https://as.example.com",
  "iat": 1710000000,
  "exp": 1710000300,
  "jti": "f1f7c8c4-2f8c-4c6a-83d1-example",
  "txn": "97053963-771d-49cc-a4e3-20aad399c312",
  "authorization_details": [
    {
      "type": "payment",
      "actions": ["initiate"],
      "locations": ["https://payments.example.com/accounts/123"],
      "instructedAmount": {
        "currency": "GBP",
        "amount": "5000.00"
      },
      "creditorName": "Example Ltd"
    }
  ],
  "reason": "Approval is required before initiating this payment.",
  "reason_uri": "https://resource.example.com/transactions/97053963-771d-49cc-a4e3-20aad399c312",
  "act": {
    "sub": "spiffe://example.com/aiagent/6526f880-1895-400b-a929-11a7eecf9753"
  }
}

4.3. Challenge Signing and Key Discovery

A protected resource that issues transaction authorization challenges MUST sign each challenge using an asymmetric signing key. The client and authorization server MUST validate the challenge signature before using any claim from the challenge for an authorization decision or for display to the user.¶

A protected resource that issues transaction authorization challenges MUST make the public keys needed to validate those challenges available to clients and authorization servers. This document defines protected resource metadata parameters, using the OAuth 2.0 Protected Resource Metadata mechanism described in [OAUTH-PROT-METADATA]. Deployments MAY also use preconfigured trust relationships or other mechanisms to establish the same keying information.¶

This document defines the following protected resource metadata parameters:¶

txn_challenge_jwks_uri:

URL of the protected resource's JSON Web Key Set containing public keys used to validate transaction authorization challenges.¶

txn_challenge_signing_alg_values_supported:

JSON array containing the JWS alg values supported by the protected resource for transaction authorization challenges.¶

If a protected resource uses the same JWK Set for transaction authorization challenges and for other protected resource signing keys, the value of txn_challenge_jwks_uri MAY be the same as another JWK Set URI published by the protected resource.¶

When the challenge-signing key is published in the JWK Set identified by txn_challenge_jwks_uri, the kid value in the JOSE header of a transaction authorization challenge MUST identify the signing key in that JWK Set.¶

If the challenge cannot be validated, the client or authorization server MUST NOT treat the challenge as authentic.¶

4.4. Agent Relay

After receiving a transaction authorization challenge from a protected resource, the agent relays the challenge to the client using a deployment-specific client-agent protocol.¶

The agent MUST relay the transaction authorization challenge without modifying it and MUST NOT replace it with an agent-generated description of the requested operation. The client MUST treat any agent-supplied description as advisory. Any authorization decision, user display, or disclosure decision MUST be based on the validated challenge or on protected resource state identified by the validated challenge.¶

A client-agent protocol that carries transaction authorization challenges SHOULD distinguish a transaction authorization challenge from ordinary agent messages or natural-language content. For example, such a protocol can carry the challenge using a field named transaction_challenge whose value is the JWS Compact Serialization of the transaction authorization challenge.¶

In deployments where one agent delegates work to another agent, a transaction authorization challenge MAY be relayed through one or more intermediate agents before reaching the client. Each agent that relays the challenge MUST relay it without modification. An intermediate agent MUST NOT replace the challenge with a new challenge unless it is itself acting as a protected resource for a distinct operation and generates a new signed transaction authorization challenge for that operation.¶

4.5. Client Processing

Before presenting the challenge to the authorization server, the client MUST validate the challenge signature, issuer, audience, and expiration. The client MUST verify that the aud claim identifies the authorization server to which the client intends to present the challenge.¶

The client MAY display the challenge contents to the user before sending the challenge to the authorization server. This allows the user to decide whether to continue and whether to disclose the challenged transaction to the authorization server.¶

When displaying challenge information, the client MUST use information obtained from the validated challenge or from protected resource state identified by the validated challenge. The client MUST NOT rely on an unprotected description supplied by the agent.¶

If the user declines to continue, or if the client cannot validate the challenge, the client MUST NOT present the challenge to the authorization server.¶

4.6. Authorization Server Processing

The authorization server MUST validate the transaction authorization challenge before accepting it for processing or issuing a transaction token.¶

At a minimum, the authorization server MUST verify that:¶

• the challenge signature is valid;¶

• the challenge was issued by a protected resource recognized by the authorization server;¶

• the challenge has not expired;¶

• the aud claim identifies the authorization server;¶

• the authorization server is willing to issue transaction tokens for the protected resource identified by the iss claim and for the requested operation;¶

• the transaction token issued in response to the challenge will use the protected resource identified by the iss claim as its audience, unless an application profile defines a different audience binding;¶

• the txn claim is present, is a string, and is acceptable;¶

• the requested operation is sufficiently described;¶

• the client is permitted to request transaction authorization for the challenged operation.¶

When requester context, such as the act claim, is present in the challenge, the authorization server MUST consider that context when determining whether the challenged operation can be approved.¶

The authorization server determines the approving party according to local policy. The approving party can be the subject associated with the original request, a different resource owner, an administrator, an organizational approval workflow, or another policy authority.¶

The authorization server MUST obtain any required approval before issuing a transaction token. The authorization server SHOULD present the approving party with sufficient information to understand the operation being authorized. The authorization server MUST NOT rely on an unprotected description supplied by the agent as the basis for the authorization decision.¶

If the authorization server accepts the challenge for processing, the client obtains the result using the transaction authorization flow described in Section 5. If the authorization server rejects the challenge, cannot validate the challenge, or cannot obtain the required approval, it MUST NOT issue a transaction token for the challenged operation.¶

5.1. Transaction Authorization Request

This specification defines a new OAuth endpoint: the transaction authorization endpoint. The authorization server MUST publish the location of the transaction authorization endpoint using the transaction_authorization_endpoint authorization server metadata parameter defined by this document.¶

The client makes a transaction authorization request to the transaction authorization endpoint by sending a POST request with the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body:¶

client_id:

REQUIRED if the client is not authenticating with the authorization server as described in Section 3.2.1 of [OAUTH-FRAMEWORK]. The client identifier issued to the client during the registration process.¶

transaction_challenge:

REQUIRED. The transaction authorization challenge received from the protected resource.¶

For example, the client makes the following HTTPS request:¶

POST /txn-authorization HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3
&transaction_challenge=eyJhbGciOiJFUzI1NiIsInR5cCI6InR4bi1hdXRoei1jaGFsbGVuZ2Urand0...

Requests to the transaction authorization endpoint MUST use the Transport Layer Security (TLS) protocol [TLS] and implement the best practices of [BCP-195].¶

The client authentication requirements of Section 3.2.1 of [OAUTH-FRAMEWORK] apply to requests on this endpoint, which means that confidential clients (those that have established client credentials) authenticate in the same manner as when making requests to the token endpoint, and public clients provide the "client_id" parameter to identify themselves.¶

The authorization server MUST validate the transaction authorization challenge as described in Section 4.6 before accepting the request for processing.¶

5.2. Transaction Authorization Response

After receiving a transaction authorization request, the authorization server validates the transaction authorization challenge as described in Section 4.6. The authorization server then either issues a transaction token, indicates that the transaction authorization request is pending, or returns an error response.¶

If the authorization server approves the challenged operation without additional interaction, it returns a transaction token response as described in Section 5.4.¶

If additional interaction or policy evaluation is required, the authorization server returns an HTTP 200 response with an application/json body containing the following parameters:¶

transaction_authorization_id:

REQUIRED. A server-generated identifier used by the client to continue or poll the transaction authorization request.¶

expires_in:

REQUIRED. Lifetime in seconds of the pending transaction authorization request maintained by the authorization server.¶

interval:

OPTIONAL. Minimum amount of time in seconds that the client SHOULD wait between polling requests. If omitted, the client SHOULD use 5 seconds.¶

authorization_uri:

OPTIONAL. URI that the client can present to the user or open in a user agent to continue the authorization interaction. This URI is used when the authorization server requires an interactive approval or authentication step.¶

The authorization server MUST bind the transaction_authorization_id to the client that initiated the transaction authorization request.¶

A successful response containing transaction_authorization_id does not indicate that the challenged operation has been approved. It only indicates that the authorization server has accepted the transaction authorization request for processing.¶

For example:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "transaction_authorization_id": "txn-authz-abc123",
  "expires_in": 300,
  "interval": 5
}

The following example includes an authorization_uri for an authorization interaction:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "transaction_authorization_id": "txn-authz-abc123",
  "authorization_uri": "https://as.example.com/txn-authorization/txn-authz-abc123",
  "expires_in": 300,
  "interval": 5
}

5.3. Pending and Polling

If the authorization server returns a transaction_authorization_id, the client continues the transaction authorization request by polling the transaction authorization endpoint.¶

The client polls by sending a POST request with the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body:¶

client_id:

REQUIRED if the client is not authenticating with the authorization server as described in Section 3.2.1 of [OAUTH-FRAMEWORK]. The client identifier issued to the client during the registration process.¶

transaction_authorization_id:

REQUIRED. The transaction authorization identifier returned by the authorization server.¶

For example:¶

POST /txn-authorization HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3
&transaction_authorization_id=txn-authz-abc123

The client MUST wait at least the number of seconds specified by the interval parameter before polling again. If no interval value was provided, the client MUST wait at least 5 seconds between polling requests.¶

The authorization server MUST ensure that the client polling the transaction authorization endpoint is the same client that initiated the transaction authorization request, or is otherwise authorized to obtain the result.¶

If the transaction authorization request is still pending, the authorization server returns an error response with the authorization_pending error code, as defined in Section 3.5 of [OAUTH-DEVICE].¶

For example:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error": "authorization_pending"
}

The authorization server MAY return an error response with the slow_down error code, as defined in Section 3.5 of [OAUTH-DEVICE], to instruct the client to increase the polling interval. After receiving slow_down, the client MUST increase the polling interval by at least 5 seconds.¶

On encountering a connection timeout, clients MUST unilaterally reduce their polling frequency before retrying. The use of an exponential backoff algorithm to achieve this, such as doubling the polling interval on each such connection timeout, is RECOMMENDED.¶

If the transaction authorization request is approved, the authorization server returns a transaction token response as described in Section 5.4.¶

If the approving party denies the request, the authorization server returns an error response with the access_denied error code. If the transaction authorization request has expired, the authorization server returns an error response with the expired_token error code, as defined in Section 3.5 of [OAUTH-DEVICE].¶

5.4. Successful Transaction Token Response

If the transaction authorization request is approved, the authorization server returns a transaction token response.¶

The transaction token response uses the response format defined by [TXN-TOKENS]. The transaction token MUST contain the txn value from the transaction authorization challenge. The transaction token MUST use the iss value from the transaction authorization challenge as its audience unless an application profile defines a different audience binding.¶

For example:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR4bnRva2VuK2p3dCJ9...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:txn_token",
  "token_type": "N_A"
}

6.1. Token Presentation

The client provides the transaction token to the agent. The agent presents the transaction token to the protected resource together with the request for the challenged operation.¶

In deployments where one agent delegates work to another agent, the transaction token MAY be relayed through one or more intermediate agents before being presented to the protected resource. Each agent that relays the transaction token MUST relay it without modification. An agent MUST NOT use the transaction token for a different transaction, different protected resource, or different requester context.¶

When HTTP is used, the transaction token MUST be presented using the Txn-Token header field defined by [TXN-TOKENS].¶

For example:¶

POST /payments HTTP/1.1
Host: resource.example.com
Authorization: Bearer mF_9.B5f-4.1JqM
Txn-Token: eyJhbGciOiJFUzI1NiIsInR5cCI6InR4bnRva2VuK2p3dCJ9...
Content-Type: application/json

{
  "amount": "5000.00",
  "currency": "GBP",
  "recipient": "Example Ltd"
}

The agent MUST NOT modify the transaction token. If the agent cannot present the transaction token to the protected resource, the challenged operation cannot be completed using this mechanism.¶

6.2. Protected Resource Validation

Before accepting a transaction token as authorization for a challenged operation, the protected resource MUST validate the transaction token according to [TXN-TOKENS] and the requirements of this document.¶

At a minimum, the protected resource MUST verify that:¶

• the transaction token was issued by the authorization server identified by the aud claim of the transaction authorization challenge;¶

• the transaction token audience identifies the protected resource, unless an application profile defines a different audience binding;¶

• the transaction token has not expired;¶

• the transaction token contains the same txn value as the transaction authorization challenge;¶

• the transaction token authorizes the requested operation;¶

• any requester context required by the transaction authorization challenge is present and matches the challenged transaction;¶

• the transaction token has not previously been used, if the protected resource requires single-use transaction tokens.¶

A protected resource MUST reject a transaction token that does not correspond to the transaction authorization challenge for the requested operation.¶

A protected resource SHOULD treat transaction tokens as single-use when the challenged operation is non-idempotent or high impact. If single-use semantics are required, the protected resource MUST maintain sufficient state to detect replay of the transaction token or transaction identifier.¶

The protected resource MUST NOT accept a transaction token as general authorization for operations other than the challenged operation.¶

8.1. HTTP Field Name Registration

IANA is requested to register the following field name in the "HTTP Field Name" registry [IANA.HTTP.FieldNames] as a structured Header Field:¶

Field Name:

Accept-Txn-Challenge¶

Status:

permanent¶

Structured Type:

Item¶

Reference:

this document¶

8.2. OAuth Extensions Error Registration

IANA is requested to register the following error value in the "OAuth Extensions Error" registry [IANA.OAuth.Parameters]:¶

Error name:

transaction_authorization_required¶

Usage location:

resource access error response¶

Protocol extension:

OAuth Transaction Authorization Challenge¶

Change controller:

IETF¶

Reference:

this document¶

8.3. OAuth Parameter Registration

IANA is requested to register the following parameters in the "OAuth Parameters" registry [IANA.OAuth.Parameters]:¶

Name:

transaction_challenge¶

Parameter Usage Location:

rs-client response, transaction authorization request¶

Change controller:

IETF¶

Reference:

this document¶

Name:

transaction_authorization_id¶

Parameter Usage Location:

transaction authorization request, transaction authorization response¶

Change controller:

IETF¶

Reference:

this document¶

8.4. OAuth Protected Resource Metadata Registration

IANA is requested to register the following values in the "OAuth Protected Resource Metadata" registry [IANA.OAuth.Parameters].¶

Metadata name:

txn_challenge_jwks_uri¶

Metadata description:

URL of the protected resource's JSON Web Key Set containing public keys used to validate transaction authorization challenges.¶

Change controller:

IETF¶

Reference:

this document¶

Metadata name:

txn_challenge_signing_alg_values_supported¶

Metadata description:

JSON array containing the JWS alg values supported by the protected resource for transaction authorization challenges.¶

Change controller:

IETF¶

Reference:

this document¶

8.5. OAuth Authorization Server Metadata Registration

IANA is requested to register the following value in the "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters].¶

Metadata name:

transaction_authorization_endpoint¶

Metadata description:

URL of the authorization server endpoint to which clients submit transaction authorization challenges.¶

Change controller:

IETF¶

Reference:

this document¶

8.6. JSON Web Token Claims Registration

IANA is requested to register the following claims in the "JSON Web Token Claims" registry [IANA.JSON.Web.Token].¶

Claim Name:

reason¶

Claim Description:

Human-readable explanation of why authorization, confirmation, or other processing is required.¶

Change Controller:

IETF¶

Reference:

this document¶

Claim Name:

reason_uri¶

Claim Description:

URI identifying additional information about why authorization, confirmation, or other processing is required.¶

Change Controller:

IETF¶

Reference:

this document¶

9.1. Normative References

[BCP-195]

Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", RFC 7525, DOI 10.17487/RFC7525, May 2015, <https://www.rfc-editor.org/rfc/rfc7525>.

[JWS]

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>.

[JWT]

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>.

[OAUTH-DEVICE]

Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Authorization Grant", RFC 8628, DOI 10.17487/RFC8628, August 2019, <https://www.rfc-editor.org/rfc/rfc8628>.

[OAUTH-FRAMEWORK]

Hardt, D., "The OAuth 2.0 Authorization Framework", Work in Progress, Internet-Draft, draft-ietf-oauth-v2-31, 1 August 2012, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-31>.

[OAUTH-PROT-METADATA]

Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, <https://www.rfc-editor.org/rfc/rfc9728>.

[OAUTH-RAR]

Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, <https://www.rfc-editor.org/rfc/rfc9396>.

[OAUTH-TOKEN-EXCHANGE]

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>.

[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>.

[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>.

[SET]

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>.

[STRUCTURED-FIELDS]

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>.

[TXN-TOKENS]

Tulshibagwale, A., Fletcher, G., and P. Kasselman, "Transaction Tokens", Work in Progress, Internet-Draft, draft-ietf-oauth-transaction-tokens-08, 2 March 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-transaction-tokens-08>.

9.2. Informative References

[IANA.HTTP.FieldNames]

"Hypertext Transfer Protocol (HTTP) Field Name Registry", n.d., <https://www.iana.org/assignments/http-fields/>.

[IANA.JSON.Web.Token]

"JSON Web Token (JWT)", n.d., <https://www.iana.org/assignments/jwt/>.

[IANA.OAuth.Parameters]

"OAuth Parameters", n.d., <https://www.iana.org/assignments/oauth-parameters/>.

[OAUTH-STEP-UP]

Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up Authentication Challenge Protocol", RFC 9470, DOI 10.17487/RFC9470, September 2023, <https://www.rfc-editor.org/rfc/rfc9470>.

[TLS]

Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", Work in Progress, Internet-Draft, draft-ietf-tls-rfc8446bis-14, 13 September 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-tls-rfc8446bis-14>.