Agent-to-Wallet Protocol for Digital Credentials (A2WP)

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

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

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

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

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

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

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, 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.1. Methods and Responses

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

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

{
  "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"
}

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

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

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

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