thilinasenarath97@gmail.com

Network Working Group digital credentials AI agents wallet A2WP OpenID4VCI OpenID4VP 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.

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

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.

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 when, and only when, they appear in all capitals, as shown here.

Agent

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.

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.

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 or equivalent trusted deployment configuration. The Agent MUST use a supported operation and mapping combination. The mappings in define the combinations used by this document. Supporting the A2WP core does not require supporting both mappings. Cancellation requests have the behavior in ; a Wallet can reject cancellation when it cannot safely stop an operation.

Information Model Messages are JSON objects . 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 .

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.

Operation Representation

operation_id

REQUIRED opaque string identifying the operation within the Wallet.

operation and protocol

REQUIRED strings identifying the accepted operation and mapping.

status

REQUIRED string with a value defined in .

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 .

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.

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.

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.

Credential Operations

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.

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

The Wallet has stopped the operation with the guarantees in .

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.

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.

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

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.

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.

OpenID4VCI Acquisition The identifier openid4vci selects acquire using OpenID for Verifiable Credential Issuance 1.0 . 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.

OpenID4VP Presentation The identifier openid4vp selects present using OpenID for Verifiable Presentations 1.0 . 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, 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.

HTTPS Binding The HTTP binding uses HTTPS 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.

Methods and Responses

Request	Response
POST operation endpoint	202 and an operation representation if nonterminal; 201 and a representation if already terminal. Location identifies the status URI.
GET status URI	200 and the current representation, including when the operation itself has failed.
DELETE status URI	200 and the cancelled representation, or 409 with not-cancellable. Cancellation does not remove the status resource.
POST query endpoint	200 and a query response.

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.

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. In the OAuth profile, the Wallet is an OAuth 2.0 Protected Resource and validates tokens for the Wallet resource and requested access. Implementations MUST follow applicable OAuth security requirements . Bearer use follows . Sender-constrained tokens are RECOMMENDED; when DPoP is used, the Agent and Wallet MUST follow , 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.

Wallet Metadata Wallet selection and initial configuration are deployment-specific. The OAuth profile SHOULD publish A2WP capabilities using Protected Resource Metadata . 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.

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

The Wallet cannot provide the cancellation guarantees for this operation.

The HTTP binding MUST use Problem Details 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.

Security Considerations

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.

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.

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.

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

IANA Considerations This document requests the following registrations in the OAuth Protected Resource Metadata registry established by . No registration is requested for the application-specific OAuth scope values or JSON error codes defined here.

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)

of this document.

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)

of this document.

a2wp_protocols_supported

Metadata Name

a2wp_protocols_supported

Metadata Description

JSON array of external-protocol mapping identifiers supported by the Wallet.

Change Controller

IETF

Specification Document(s)

of this document.

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)

of this document.

Normative References

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 . 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. 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: If the Wallet instead loses confirmation of the external outcome and stops processing, status retrieval still succeeds with HTTP 200, but returns: