Agent-to-Wallet Protocol for Digital Credentials (A2WP)
draft-senarath-a2wp-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Thilina | ||
| Last updated | 2026-09-19 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-senarath-a2wp-00
Network Working Group T. S. Senarath
Internet-Draft 19 September 2026
Intended status: Standards Track
Expires: 23 March 2027
Agent-to-Wallet Protocol for Digital Credentials (A2WP)
draft-senarath-a2wp-00
Abstract
This document defines the Agent-to-Wallet Protocol (A2WP), an
interface through which a software Agent requests digital credential
operations from a Wallet. A2WP supports credential acquisition,
presentation, and optional queries for authorized credential
metadata. The Wallet controls credential selection, disclosure,
approval, and cryptographic execution.
A2WP defines an information model, observable operation behavior, and
an HTTPS binding. Credential formats, Agent identity schemes,
delegation mechanisms, policy languages, and Wallet internals are
outside its scope. External credential protocols are integrated
through protocol mappings.
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/.
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 23 March 2027.
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
Senarath Expires 23 March 2027 [Page 1]
Internet-Draft A2WP September 2026
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 . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3
3. Interaction Model . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Supported Capabilities . . . . . . . . . . . . . . . . . 5
4. Information Model . . . . . . . . . . . . . . . . . . . . . . 5
4.1. Operation Request . . . . . . . . . . . . . . . . . . . . 5
4.2. Operation Representation . . . . . . . . . . . . . . . . 5
4.3. Interaction . . . . . . . . . . . . . . . . . . . . . . . 6
4.4. Credential Metadata . . . . . . . . . . . . . . . . . . . 7
5. Credential Operations . . . . . . . . . . . . . . . . . . . . 7
5.1. Creation and Retrieval . . . . . . . . . . . . . . . . . 7
5.2. Observable Status . . . . . . . . . . . . . . . . . . . . 7
5.3. Cancellation . . . . . . . . . . . . . . . . . . . . . . 8
5.4. Retries and Retention . . . . . . . . . . . . . . . . . . 8
6. Optional Credential Query . . . . . . . . . . . . . . . . . . 9
7. External Protocol Mappings . . . . . . . . . . . . . . . . . 10
7.1. OpenID4VCI Acquisition . . . . . . . . . . . . . . . . . 10
7.2. OpenID4VP Presentation . . . . . . . . . . . . . . . . . 10
8. HTTPS Binding . . . . . . . . . . . . . . . . . . . . . . . . 11
8.1. Methods and Responses . . . . . . . . . . . . . . . . . . 12
8.2. Access Protection and OAuth Profile . . . . . . . . . . . 12
8.3. Wallet Metadata . . . . . . . . . . . . . . . . . . . . . 13
9. Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
10. Security Considerations . . . . . . . . . . . . . . . . . . . 15
10.1. Authorization Boundary . . . . . . . . . . . . . . . . . 15
10.2. References and Network Access . . . . . . . . . . . . . 16
10.3. Data Minimization . . . . . . . . . . . . . . . . . . . 16
11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 16
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
12.1. a2wp_operation_endpoint . . . . . . . . . . . . . . . . 17
12.2. a2wp_operations_supported . . . . . . . . . . . . . . . 17
12.3. a2wp_protocols_supported . . . . . . . . . . . . . . . . 17
12.4. a2wp_credential_query_endpoint . . . . . . . . . . . . . 18
13. Normative References . . . . . . . . . . . . . . . . . . . . 18
Appendix A. Example Operation Exchange . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21
Senarath Expires 23 March 2027 [Page 2]
Internet-Draft A2WP September 2026
1. Introduction
An Agent carrying out a task can encounter a credential offer or a
request to prove an attribute. A2WP provides a common interface for
asking a Wallet to process that interaction. The Agent expresses
credential intent; the Wallet exercises credential authority.
This separation is useful when an Agent processes untrusted
instructions or content. The Wallet independently decides whether
the requested operation is permitted and executes the applicable
credential protocol. Credentials and presentations need not enter
the Agent's model context.
Agent -- A2WP --> Wallet -- Issuance --> Issuer
|
+---- Presentation --> Verifier
An Agent may act for a person, organization, or service. It need not
be the credential subject or Holder. A2WP can also be used by
software clients that do not use a language model.
1.1. Scope
This specification standardizes the messages exchanged between an
Agent and a Wallet and the outcomes visible to the Agent. Wallet
architecture, storage, internal state management, policy evaluation,
credential selection algorithms, approval workflows, and user
interfaces are implementation concerns.
A2WP does not define how authority is delegated to an Agent, how a
remote service authorizes a business transaction, or how a credential
proves the identity of an Agent. It provides no private-key export,
credential export, or general-purpose signing operation.
The information model is independent of transport. This document
defines an HTTPS binding and two external-protocol mappings. Other
bindings and mappings can be defined separately. Their requirements
do not extend to implementations that do not support them.
2. Conventions and Terminology
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.
Agent
Senarath Expires 23 March 2027 [Page 3]
Internet-Draft A2WP September 2026
Software acting as an A2WP client, including an Agent runtime or
orchestrator.
Principal
The person, organization, service, or other entity whose authority
applies to an operation. Establishing the Agent's relationship to
a Principal is outside this specification.
Wallet
The A2WP service responsible for credential operations and their
authorization. It may use other trusted components to perform its
functions.
Credential
A cryptographically protected set of claims issued by an Issuer.
Holder, Issuer, and Verifier
The Holder is the entity on whose behalf credentials are held and
presented. The Issuer issues credentials; the Verifier requests
or evaluates presentations. The Holder need not be the credential
subject.
Credential Handle
An opaque Wallet-generated reference to a credential. Possession
of a handle grants no authority.
Operation
A Wallet-managed acquisition or presentation with an identifier
and observable status. It may finish immediately or
asynchronously.
Protocol Mapping
A specification associating a protocol identifier with allowed
operations, request data, and completion semantics.
3. Interaction Model
The Agent submits a credential request. The Wallet determines the
applicable authorization, selects permitted credentials or issuance
options, obtains any required approval, and performs the external
protocol. The Agent can retrieve the resulting operation state and
request cancellation. These steps do not prescribe the Wallet's
internal workflow.
The Wallet MUST authorize credential queries, operation creation,
status retrieval, and cancellation in the applicable authenticated
Agent and Principal context. The mechanism establishing this context
is deployment-specific. An Agent-supplied identifier or purpose
statement MUST NOT by itself establish authority.
The Agent and Wallet are separate trust domains even when deployed
together. The Wallet MUST retain control of credential private keys
and MUST NOT return those keys, complete credentials, or
presentations in A2WP responses. These restrictions also apply to
extension fields and error details.
Senarath Expires 23 March 2027 [Page 4]
Internet-Draft A2WP September 2026
3.1. Supported Capabilities
A conforming Wallet MUST support at least one of acquire or present
with a defined protocol mapping, and MUST support operation creation
and status retrieval. Credential query is OPTIONAL. A Wallet MUST
expose its supported operations and mappings through the metadata in
Section 8.3 or equivalent trusted deployment configuration. The
Agent MUST use a supported operation and mapping combination.
The mappings in Section 7 define the combinations used by this
document. Supporting the A2WP core does not require supporting both
mappings. Cancellation requests have the behavior in Section 5.3; a
Wallet can reject cancellation when it cannot safely stop an
operation.
4. Information Model
Messages are JSON objects [RFC8259]. Member names and identifier
values are case-sensitive. Required members MUST be present and have
the specified types; explicit null does not substitute for an omitted
optional member. Duplicate member names MUST be rejected. Timestamp
fields defined here are strings in the date-time format of [RFC3339].
4.1. Operation Request
operation
REQUIRED string: acquire, present, or an operation identifier
defined by an agreed extension.
protocol
REQUIRED string identifying the applicable protocol mapping.
request
REQUIRED object whose contents are defined by the mapping.
context
OPTIONAL object containing advisory application context. Its
properties are deployment-specific; task_id and purpose in the
examples are illustrative, not standardized authorization
attributes.
The Wallet MUST treat Agent-supplied context as untrusted. It MAY
use such information for explanation, correlation, or auditing
subject to policy. The presence or absence of context MUST NOT
replace authorization.
4.2. Operation Representation
operation_id
REQUIRED opaque string identifying the operation within the
Wallet.
Senarath Expires 23 March 2027 [Page 5]
Internet-Draft A2WP September 2026
operation and protocol
REQUIRED strings identifying the accepted operation and mapping.
status
REQUIRED string with a value defined in Section 5.2.
status_uri
REQUIRED in the HTTPS binding: an absolute HTTPS URI for
retrieving the operation. Other bindings define their own
retrieval mechanism.
interaction
OPTIONAL object describing a required interaction; permitted only
while status is interaction_required.
result
OPTIONAL object containing authorized result information defined
by the mapping; permitted only when status is completed.
error
REQUIRED when status is failed, otherwise absent. An error object
as defined in Section 9.
completed_at
OPTIONAL timestamp indicating when the operation entered a
terminal state.
expires_at
OPTIONAL timestamp after which the Wallet will no longer attempt
to complete a nonterminal operation. It does not specify how long
its status remains retrievable.
The operation identifier, operation type, and mapping MUST remain
unchanged during the operation's lifetime. A status response
describes the Wallet's current view; an Agent may observe only some
intermediate states. A Wallet MUST apply disclosure policy to every
representation, including results and errors.
4.3. Interaction
An interaction object contains an OPTIONAL interaction_uri string and
an OPTIONAL expires_at timestamp. The URI identifies a Wallet-
authorized interaction entry point for an appropriate actor or
application. Additional interaction properties are deployment-
specific.
The Wallet arranges the approval or other interaction. If no URI is
returned, the Agent can continue polling while the interaction occurs
through another channel. The Agent MUST NOT assume that receiving a
URI authorizes it to complete the interaction. A2WP does not
standardize the interaction UI, its authentication mechanism, or a
separate approval endpoint.
Senarath Expires 23 March 2027 [Page 6]
Internet-Draft A2WP September 2026
4.4. Credential Metadata
A Credential Metadata object contains a REQUIRED credential_handle
string and an OPTIONAL properties object. Properties describe the
credential using names and value semantics agreed by a deployment or
profile. This specification does not define a cross-format
credential taxonomy.
Handles MUST be opaque and MUST NOT embed credential claims. Wallets
SHOULD scope handles to the authorized Agent and Principal context to
limit correlation. A handle is a reference for correlation; this
base specification does not define Agent-directed credential
selection by handle. A later query need not return the same handle.
5. Credential Operations
5.1. Creation and Retrieval
The Wallet validates and authorizes an operation request before
accepting it. An accepted request creates an operation and returns
its representation. Acceptance does not imply that disclosure has
been approved or that the external protocol has succeeded. The Agent
retrieves subsequent representations using the mechanism defined by
the binding; in the HTTPS binding, this is the returned status URI.
An acquire operation asks the Wallet to obtain and retain
credentials. A present operation asks the Wallet to respond to an
external presentation request. The applicable mapping defines the
request data and the completion point. The Wallet remains
responsible for credential selection and disclosure.
5.2. Observable Status
pending
Accepted and waiting to proceed, without a currently reported
interaction requirement.
interaction_required
Waiting for an action outside the operation's automatic
processing. The interaction mechanism remains under Wallet
control.
processing
The Wallet is attempting to perform the operation.
completed
The completion conditions of the selected mapping have been met.
failed
The Wallet has stopped processing without establishing successful
completion. Failure does not imply absence of external effects.
cancelled
Senarath Expires 23 March 2027 [Page 7]
Internet-Draft A2WP September 2026
The Wallet has stopped the operation with the guarantees in
Section 5.3.
The first three states are nonterminal. A Wallet MAY move among them
as processing requires, or enter a terminal state. The last three
states are terminal and MUST NOT transition to another state. An
operation can be terminal in its first returned representation.
These states describe externally observable behavior, not the
Wallet's internal execution model.
If an operation or interaction expires before completion, the Wallet
MUST stop further processing and report failed. It uses the
appropriate expiry code unless it cannot determine whether an
external action succeeded, in which case it MUST use outcome-unknown.
The same uncertainty rule applies to other failures. A timeout alone
is not evidence that no disclosure or issuance occurred.
Completion of presentation does not by itself establish that the
Verifier accepted the claims, authorized a business transaction, or
associated that transaction with the Agent. Those guarantees belong
to the external protocol or application integration.
5.3. Cancellation
An Agent MAY request cancellation of any nonterminal operation. The
Wallet MUST authorize the request and either return a cancelled
representation or reject cancellation. It MUST NOT report
cancellation if a presentation has already been submitted, an
acquired credential has already been retained, or it cannot ensure
that these actions have stopped. Rejected cancellation does not
change the operation state.
After reporting cancelled, the Wallet MUST NOT continue the requested
acquisition or presentation. Cancellation does not undo earlier
network interactions. Repeating cancellation of a cancelled
operation returns its cancelled representation. A completed or
failed operation cannot be cancelled. Operation status remains
retrievable according to the Wallet's retention policy.
5.4. Retries and Retention
Operation creation is not idempotent in this base specification. If
acceptance is uncertain after a connection failure, the Agent MUST
NOT automatically repeat the request unless an agreed extension
provides safe duplicate handling. Advisory context, including a task
identifier, is not a deduplication mechanism.
Senarath Expires 23 March 2027 [Page 8]
Internet-Draft A2WP September 2026
An Agent can retry status retrieval. Operation retention periods and
internal recovery mechanisms are implementation concerns. After
retention ends, the Wallet can report the operation as unavailable.
An unavailable status MUST NOT be interpreted as proof that the
operation did not execute.
6. Optional Credential Query
A query requests only metadata the Agent is permitted to discover.
Query authorization is independent of acquisition or presentation
authorization. A Wallet MUST NOT infer permission to disclose an
inventory from permission to present a credential.
The request is an object with OPTIONAL filter and cursor members. A
filter is an object whose vocabulary and matching semantics are
specified by a deployment or profile. A cursor is a string. A
Wallet MUST reject a filter it does not support rather than silently
broaden the query. With no filter, the request covers the metadata
visible to the Agent under policy.
The response contains a REQUIRED credentials array of Credential
Metadata objects, which can be empty. If more results remain, it
MUST include a next_cursor string. The Agent continues by sending
that value as cursor with the same filter. Cursors are opaque, bound
to the authorized query context, and do not grant access. Page size,
cursor lifetime, ordering, and snapshot consistency are
implementation concerns; unsupported or expired cursors produce
invalid-request.
The response is not a promise that any returned credential can
satisfy a future presentation. Querying is not a prerequisite to
requesting presentation. The examples below use an unfiltered query
and no deployment-specific metadata properties.
{}
{
"credentials": [
{
"credential_handle": "cred_d4R7vN2kL9pT5mQ8sH1c6A"
}
]
}
Senarath Expires 23 March 2027 [Page 9]
Internet-Draft A2WP September 2026
7. External Protocol Mappings
A protocol mapping defines its identifier, allowed operation types,
request object, completion conditions, and any result members. It
also identifies its supported external protocol variants. A Wallet
MUST apply the external protocol's validation and security
requirements; a mapping does not authorize bypassing them. Other
mappings can be specified independently of the A2WP core.
7.1. OpenID4VCI Acquisition
The identifier openid4vci selects acquire using OpenID for Verifiable
Credential Issuance 1.0 [OPENID4VCI]. The request MUST contain
exactly one of credential_offer, an object containing a Credential
Offer, or credential_offer_uri, an HTTPS URI string referencing an
offer. Offer processing follows the external protocol.
The Wallet chooses the permitted issuance options and handles
authentication, transaction-code entry, and deferred issuance. Where
an interaction is needed, it uses interaction_required. A deferred
response does not complete acquisition. An unsupported offer or
required protocol feature produces unsupported-protocol.
The operation completes when the Wallet has obtained, validated as
required by the external protocol and its policy, and stored all
credentials it undertook to acquire. A partial acquisition MUST NOT
be reported as completed. If multiple credentials are involved,
failure does not imply that already stored credentials were rolled
back. Authorized metadata MAY be returned in a result.credentials
array; omission of metadata does not negate completion.
{
"operation": "acquire",
"protocol": "openid4vci",
"request": {
"credential_offer_uri": "https://issuer.example/offers/9F4E"
}
}
7.2. OpenID4VP Presentation
The identifier openid4vp selects present using OpenID for Verifiable
Presentations 1.0 [OPENID4VP]. The request object carries the outer
Authorization Request parameters as string-valued members.
Parameters received in a query string are URL-decoded once; JSON-
valued parameters remain serialized JSON strings. A Request Object
in request remains its encoded string value, and a reference remains
request_uri. The Agent MUST preserve all received parameters,
Senarath Expires 23 March 2027 [Page 10]
Internet-Draft A2WP September 2026
including client_id and any request_uri_method.
This mapping supports the direct_post and direct_post.jwt response
modes. The Wallet MUST validate the request, including applicable
outer-parameter and Request Object consistency rules, under
OpenID4VP. Unsupported response modes or other required features
produce unsupported-protocol. Digital Credentials API requests
require a separate mapping that preserves their platform context.
Completion requires successful processing of a presentation response
by the Verifier's response endpoint as defined by OpenID4VP and
initiation of any required user-agent redirection. Sending an
Authorization Error Response does not complete a presentation
operation. Required interaction is arranged by the Wallet; a
Verifier continuation URI is not automatically an A2WP interaction
URI. The base mapping returns no presentation result members.
Application authorization and completion of the Verifier's subsequent
workflow remain outside this guarantee.
{
"operation": "present",
"protocol": "openid4vp",
"request": {
"client_id": "x509_san_dns:verifier.example",
"request_uri": "https://verifier.example/requests/4187",
"request_uri_method": "get"
},
"context": {
"purpose": "Present organization membership for onboarding"
}
}
8. HTTPS Binding
The HTTP binding uses HTTPS [RFC9110] and JSON with the application/
json media type. Endpoint URLs are supplied through metadata or
trusted configuration; the example paths are not fixed protocol
paths. Request bodies MUST be UTF-8 JSON objects. Unsupported media
types receive HTTP 415; malformed A2WP messages receive HTTP 400.
Responses containing credential metadata, operation representations,
or operation errors MUST include Cache-Control: no-store. Status and
interaction URIs MUST use HTTPS. The Agent MUST NOT forward Wallet
authorization credentials to a different resource or follow a
redirect with those credentials without an independently established
authorization relationship.
Senarath Expires 23 March 2027 [Page 11]
Internet-Draft A2WP September 2026
8.1. Methods and Responses
+================+==================================================+
| Request | Response |
+================+==================================================+
| POST | 202 and an operation representation if |
| operation | nonterminal; 201 and a representation if already |
| endpoint | terminal. Location identifies the status URI. |
+----------------+--------------------------------------------------+
| GET | 200 and the current representation, including |
| status | when the operation itself has failed. |
| URI | |
+----------------+--------------------------------------------------+
| DELETE | 200 and the cancelled representation, or 409 |
| status | with not-cancellable. Cancellation does not |
| URI | remove the status resource. |
+----------------+--------------------------------------------------+
| POST | 200 and a query response. |
| query | |
| endpoint | |
+----------------+--------------------------------------------------+
Table 1
The Wallet SHOULD include Retry-After when returning a nonterminal
operation. An Agent MUST respect that polling guidance when present
and SHOULD otherwise use bounded backoff. A Wallet MAY return HTTP
429 with Retry-After when limiting requests. The Wallet MUST
authorize every protected request, including requests made with
renewed credentials.
A missing, expired, or inaccessible operation MAY receive HTTP 404 to
avoid revealing its existence. This differs from an operation whose
execution expired and whose retained representation reports failed.
8.2. Access Protection and OAuth Profile
Deployments MUST authenticate and authorize access to protected
endpoints. Establishing identities, acquiring authentication
credentials, and expressing delegated authority are outside the core
protocol. Support for OAuth 2.0 is RECOMMENDED. Other mechanisms
can be agreed by deployment or profile.
Senarath Expires 23 March 2027 [Page 12]
Internet-Draft A2WP September 2026
In the OAuth profile, the Wallet is an OAuth 2.0 Protected Resource
[RFC6749] and validates tokens for the Wallet resource and requested
access. Implementations MUST follow applicable OAuth security
requirements [RFC9700]. Bearer use follows [RFC6750]. Sender-
constrained tokens are RECOMMENDED; when DPoP is used, the Agent and
Wallet MUST follow [RFC9449], including proof and token-binding
validation.
This profile defines a2wp.acquire and a2wp.present for their
corresponding operations, and a2wp.query for credential query. The
Wallet MUST require the corresponding scope for operation creation or
query. Reading or cancelling an operation requires the scope
corresponding to its type and authorization for that particular
operation. These scopes do not replace Wallet disclosure policy or
grant access to other Agents' operations.
8.3. Wallet Metadata
Wallet selection and initial configuration are deployment-specific.
The OAuth profile SHOULD publish A2WP capabilities using Protected
Resource Metadata [RFC9728]. When that mechanism is used, its
discovery and resource-identifier validation requirements apply.
Other deployments can supply these same A2WP fields through trusted
configuration.
a2wp_operation_endpoint
REQUIRED string: the absolute HTTPS URL for creating operations.
a2wp_operations_supported
REQUIRED nonempty array of distinct strings drawn from acquire and
present, or identifiers defined by an agreed extension.
a2wp_protocols_supported
REQUIRED nonempty array of distinct protocol-mapping identifier
strings. Each advertised mapping MUST be usable with at least one
advertised operation; each advertised operation MUST have at least
one applicable advertised mapping.
a2wp_credential_query_endpoint
OPTIONAL string: the absolute HTTPS URL for credential query. Its
presence advertises query support; its absence means query is not
advertised.
Senarath Expires 23 March 2027 [Page 13]
Internet-Draft A2WP September 2026
{
"resource": "https://wallet.example",
"authorization_servers": [
"https://auth.example"
],
"a2wp_operation_endpoint": "https://wallet.example/operations",
"a2wp_operations_supported": [
"acquire",
"present"
],
"a2wp_protocols_supported": [
"openid4vci",
"openid4vp"
],
"a2wp_credential_query_endpoint":
"https://wallet.example/credentials/query"
}
9. Errors
An operation error object contains a REQUIRED code string and an
OPTIONAL detail string intended for human explanation. Agents MUST
NOT use detail text as a machine-readable instruction. The following
codes are defined by this document.
invalid-request
Malformed request, unsupported filter, or inconsistent parameters.
unsupported-operation
The requested operation is not supported.
unsupported-protocol
The mapping or a required external protocol feature is not
supported for the operation.
not-authorized
The authenticated caller lacks access to the requested A2WP
resource or operation.
policy-denied
The operation or required disclosure was denied by Wallet policy
or an approving actor.
interaction-expired
A required interaction expired before completion.
operation-expired
The operation expired before completion.
external-protocol-error
The external exchange failed.
outcome-unknown
The Wallet stopped processing but cannot establish the external
outcome.
not-cancellable
Senarath Expires 23 March 2027 [Page 14]
Internet-Draft A2WP September 2026
The Wallet cannot provide the cancellation guarantees for this
operation.
The HTTP binding MUST use Problem Details [RFC9457] with media type
application/problem+json for A2WP request errors, with the error code
in a code extension member. This document uses about:blank as the
problem type and defines no error URN namespace. Authentication
challenges and errors prescribed by the selected authentication
mechanism retain their required status codes and headers.
Request errors use HTTP 400 for invalid-request, unsupported-
operation, and unsupported-protocol; HTTP 403 for not-authorized and
policy-denied; and HTTP 409 for not-cancellable. Once an operation
has been accepted, execution failures are reported in its error
member, not as a failed HTTP status retrieval. A Wallet MAY use not-
authorized instead of policy-denied when further explanation would
disclose protected information.
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"code": "not-authorized"
}
10. Security Considerations
10.1. Authorization Boundary
A compromised or manipulated Agent can request unintended credential
use. Independent Wallet authorization limits that authority but
cannot detect every misuse allowed by an overly broad policy. The
Wallet MUST authorize the actual external request, counterparty, and
disclosure before execution. Merely receiving a request, verifying a
signature, or finding a matching credential is not authorization.
When approval is required, the Wallet MUST ensure that the executed
action remains within the approved scope. Material changes to the
external request or disclosure require renewed evaluation. The
evidence and mechanisms used for authorization and approval are
implementation concerns. Agent-provided purpose text MUST be
distinguished from verified information when presented to an
approver.
A presentation establishes only what its credential and external
protocol support. Any association with an Agent's remote application
session needs the protections of that application integration. An
advisory A2WP task identifier does not establish this association.
Senarath Expires 23 March 2027 [Page 15]
Internet-Draft A2WP September 2026
10.2. References and Network Access
Knowledge of a handle, operation identifier, cursor, or interaction
URI MUST NOT by itself authorize credential use or access to status.
Operation identifiers SHOULD be unpredictable to reduce enumeration.
Wallets MUST bind protected objects to the applicable authorization
context; renewed credentials do not automatically confer access to
unrelated operations.
Wallets MUST validate untrusted external URIs and enforce deployment-
appropriate network access policy when resolving requests, metadata,
and redirects. Implementations need to account for SSRF, DNS
rebinding, unsafe schemes, and resource exhaustion. External-
protocol tokens and A2WP access credentials MUST NOT be forwarded to
unintended recipients.
Wallets SHOULD bound input sizes, external fetches, concurrent
operations, and repeated interaction requests. Appropriate limits
are deployment-specific. Cancellation, expiry, and timeouts cannot
retract information already disclosed.
10.3. Data Minimization
Credential existence, metadata, operation status, and error
differences can reveal sensitive information. Wallets MUST apply
disclosure policy to all such outputs and SHOULD return only
information needed by the Agent. Metadata properties MAY describe
authorized type, issuer, or expiry information; they MUST NOT serve
as a channel for exporting credentials or presentations.
Context, interaction links, and credential offers can contain
personal information or secrets. Wallets and Agents SHOULD minimize
their retention and avoid including sensitive values in logs and
error details. Wallets SHOULD record enough information to audit
authorization and disclosure while protecting the audit records.
This specification does not prescribe an audit schema or retention
period.
11. Extensibility
Additional operations, mappings, filters, and metadata properties can
be defined by other specifications or deployment profiles. A mapping
identifier defined by this document has the semantics stated here; an
incompatible mapping requires a different identifier. New operation
and mapping identifiers SHOULD be absolute URIs controlled by their
defining party to avoid collisions.
Senarath Expires 23 March 2027 [Page 16]
Internet-Draft A2WP September 2026
Recipients MUST ignore unrecognized optional members of A2WP
envelopes and representations. Unknown operation or mapping
identifiers MUST be rejected. Unknown filters MUST be rejected as
specified in Section 6. Processing of members inside a protocol-
specific request follows its mapping, and properties inside advisory
context have no standardized meaning.
An extension whose processing is necessary for authorization or
correct execution MUST be explicitly agreed before use, for example
through a distinct advertised mapping identifier. Such a requirement
MUST NOT be conveyed only by a field an older recipient would ignore.
Unknown response status values or error codes MUST NOT be treated as
success. Extensions MUST preserve Wallet authority and the
disclosure restrictions in Section 3.
12. IANA Considerations
This document requests the following registrations in the OAuth
Protected Resource Metadata registry established by [RFC9728].
No registration is requested for the application-specific OAuth scope
values or JSON error codes defined here.
12.1. a2wp_operation_endpoint
Metadata Name
a2wp_operation_endpoint
Metadata Description
URL of the Wallet endpoint for creating A2WP operations.
Change Controller
IETF
Specification Document(s)
Section 8.3 of this document.
12.2. a2wp_operations_supported
Metadata Name
a2wp_operations_supported
Metadata Description
JSON array of A2WP operation identifiers supported by the Wallet.
Change Controller
IETF
Specification Document(s)
Section 8.3 of this document.
12.3. a2wp_protocols_supported
Metadata Name
Senarath Expires 23 March 2027 [Page 17]
Internet-Draft A2WP September 2026
a2wp_protocols_supported
Metadata Description
JSON array of external-protocol mapping identifiers supported by
the Wallet.
Change Controller
IETF
Specification Document(s)
Section 8.3 of this document.
12.4. a2wp_credential_query_endpoint
Metadata Name
a2wp_credential_query_endpoint
Metadata Description
URL of the optional Wallet endpoint for querying credential
metadata.
Change Controller
IETF
Specification Document(s)
Section 8.3 of this document.
13. Normative References
[OPENID4VCI]
Lodderstedt, T., Yasuda, K., Looker, T., and P. Bastian,
"OpenID for Verifiable Credential Issuance 1.0", 16
September 2025, <https://openid.net/specs/openid-4-
verifiable-credential-issuance-1_0.html>.
[OPENID4VP]
Terbu, O., Lodderstedt, T., Yasuda, K., Fett, D., and J.
Heenan, "OpenID for Verifiable Presentations 1.0", 9 July
2025, <https://openid.net/specs/openid-4-verifiable-
presentations-1_0.html>.
[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/info/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>.
Senarath Expires 23 March 2027 [Page 18]
Internet-Draft A2WP September 2026
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>.
[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/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[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/info/rfc9110>.
[RFC9449] Fett, D., Campbell, B., Bradley, J., Lodderstedt, T.,
Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of
Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449,
September 2023, <https://www.rfc-editor.org/info/rfc9449>.
[RFC9457] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details
for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023,
<https://www.rfc-editor.org/info/rfc9457>.
[RFC9700] Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"Best Current Practice for OAuth 2.0 Security", BCP 240,
RFC 9700, DOI 10.17487/RFC9700, January 2025,
<https://www.rfc-editor.org/info/rfc9700>.
[RFC9728] 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/info/rfc9728>.
Appendix A. Example Operation Exchange
These examples show the OAuth profile with DPoP. Tokens and proofs
are abbreviated; message framing is omitted. The metadata has
identified https://wallet.example/operations as the operation
endpoint. The external request is represented as in Section 7.2.
Senarath Expires 23 March 2027 [Page 19]
Internet-Draft A2WP September 2026
POST /operations HTTP/1.1
Host: wallet.example
Authorization: DPoP eyJ...
DPoP: eyJ...
Content-Type: application/json
{
"operation": "present",
"protocol": "openid4vp",
"request": {
"client_id": "x509_san_dns:verifier.example",
"request_uri": "https://verifier.example/requests/4187"
}
}
The Wallet accepts the request and returns HTTP 202, a Location
header equal to the status URI, Cache-Control: no-store, and the
following representation. It can arrange interaction through its own
approval channel without returning an interaction URI.
{
"operation_id": "op_x2p9E4Hc7mR6vQ8sN1tB5A",
"operation": "present",
"protocol": "openid4vp",
"status": "interaction_required",
"status_uri":
"https://wallet.example/operations/op_x2p9E4Hc7mR6vQ8sN1tB5A"
}
The Agent subsequently polls the status URI using its authorized
access. After the mapping's completion conditions have been met, an
HTTP 200 response contains:
{
"operation_id": "op_x2p9E4Hc7mR6vQ8sN1tB5A",
"operation": "present",
"protocol": "openid4vp",
"status": "completed",
"status_uri":
"https://wallet.example/operations/op_x2p9E4Hc7mR6vQ8sN1tB5A",
"completed_at": "2026-09-19T10:22:41Z"
}
If the Wallet instead loses confirmation of the external outcome and
stops processing, status retrieval still succeeds with HTTP 200, but
returns:
Senarath Expires 23 March 2027 [Page 20]
Internet-Draft A2WP September 2026
{
"operation_id": "op_x2p9E4Hc7mR6vQ8sN1tB5A",
"operation": "present",
"protocol": "openid4vp",
"status": "failed",
"status_uri":
"https://wallet.example/operations/op_x2p9E4Hc7mR6vQ8sN1tB5A",
"error": {
"code": "outcome-unknown"
}
}
Author's Address
Thilina Shashimal Senarath
Email: thilinasenarath97@gmail.com
Senarath Expires 23 March 2027 [Page 21]