VCALM v1.0

Abstract

Verifiable credentials provide a mechanism to express credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable. This specification provides data model and HTTP protocols to issue, verify, present, and manage data used in such an ecosystem.

Goal	Description
Modularity	Implementers need only implement the APIs that are required for their use case enabling modularity between Issuing, Verifying, and Presenting.
Simplicity	The number of APIs and optionality are kept to a minimum to ensure that they are easy to implement and audit from a security standpoint.
Composability	The APIs are designed to be composable such that complex flows are possible using a small number of simple API primitives.
Extensibility	Extensions to API endpoints are expected and catered to in the API design enabling experimentation and the addition of value-added services on top of the base API platform.

One possible architecture for these software components is represented by the architecture description below, as well as the diagram in the 1.2 Architecture Overview section. These representations were chosen to make categorization of the different features in the specification clear, enabling each component to be treated independently both for clarity of reading and to highlight that each component can be implemented separately from any other. However, this is not a prescriptive architecture; implementers can use as many or as few software packages as desired to serve multiple roles; roles are not required to be served by a single library or other software package nor are software libraries or packages required to provide for particular roles in isolation of others. It is also an expectation that single deployments of software or system components can be for the purpose of multiple roles as needed for a given use case.

A coordinator executes the business rules and policies set by the associated role. Often this is a custom or proprietary coordinator developed specifically for a single party acting in that role; it is the integration glue that connects the controlling party to the verifiable credential ecosystem.

Coordinators might provide a visual user interface, depending on the implementation. Pure command-line or continuously running services might also be able to realize this component.

With the exception of the status service , all role-to-role communication is between coordinators acting on behalf of its particular actor to fulfill its role.

An issuer coordinator executes the rules about who gets what credentials, including how the parties creating or receiving those credentials are authenticated and authorized. Typically the issuer coordinator integrates the issuer 's back-end system with the issuer service . This integration uses whatever technologies are appropriate; the interfaces between the issuer coordinator and back-end services are out of scope for this specification. The issuer coordinator drives the issuer service .

A verifier coordinator communicates with a verifier service to first check authenticity and timeliness of a given verifiable credential or verifiable presentation , then applies the verifier 's business rules before ultimately accepting or rejecting that verifiable credential or verifiable presentation . Such business rules might include evaluating the issuer of a particular claim or simply checking a configured allow-list. The verifier coordinator exposes an API for submitting verifiable credentials to the verifier per the verifier 's policies. For example, the verifier coordinator might only accept verifiable credentials from current users of the verifier 's other services. These rules typically require bespoke integration with the verifier 's existing back-end.

A holder coordinator executes the business rules for approving the flow of credentials under the control of the holder , from issuers to verifiers . In some deployments this means exposing a user interface that gives individual holders a visual way to authorize or approve verifiable credential storage or transfer. Some functionality of the holder coordinator is commonly referred to as a digital wallet . In this API, the holder coordinator initiates all flows. They request verifiable credentials from issuers . They decide if, and when, to share those verifiable credentials with verifiers . Within this API, there is no way for either the issuer or the verifier to initiate the transfer of a verifiable credential . In many scenarios, the holder coordinator is expected to be under the control of an individual human, ensuring a person is directly involved in the communication of verifiable credentials , even if only at the step of authorizing the transfer. However, some verifiable credentials are about organizations, not individuals. How individuals using holder coordinator s related to organizations, and in particular, how organizational credentials are securely shared with, and presented by, (legal) agents of those organizations is not in scope for this specification.

A service provides lower-level API functionality, driven by its associated coordinator , and is designed to enable infrastructure providers to offer verifiable credential capability through service delivery architectures such as Software-as-a-Service. All services expose HTTP endpoints to their authorized coordinators , which are themselves operating on behalf of an associated role. Although deployed services might provide their own HTML interfaces, such interfaces are out of scope for this specification. Only the HTTP endpoints of services are defined herein.

An issuer service takes requests to issue verifiable credentials from authorized issuer coordinators and return conforming verifiable credentials . This service has access to cryptographic material, such as private keys or key services which utilize private keys, in order to create the proofs for verifiable credentials . The API between the issuer service and its associated cryptographic key management service is out of scope for this specification.

A verifier service takes requests to verify verifiable credentials and verifiable presentations and returns the result of checking their proofs and status (if present). The service only checks the authenticity and timeliness of the verifiable credential , leaving the verifier coordinator to finish applying any necessary business rules.

A holder service takes requests to create Verifiable Presentations from an optional set of verifiable credentials and returns well-formed, signed Verifiable Presentations containing those VCs. These verifiable presentation s are used with issuers to demonstrate control over DIDs prior to verifiable credential issuance and with verifiers to present specific VCs.

A status service provides a privacy-preserving means of publishing and checking the status of any Verifiable Credentials issued by the issuer . Implementers of verifier services are encouraged to understand the privacy implications of checking status by referring to the respective status specification used by the verifiable credential. For specific mechanisms by which to manage verifiable credential statuses, it's recommended to refer to well-known external specifications, such as the [ VC-BITSTRING-STATUS-LIST ].

A storage service is used by each actor in the system to store their own verifiable credentials and corresponding data, as needed. Several known implementations use secure data storage such as encrypted data vaults for storing the holder 's verifiable credentials and use cryptographic authorizations to grant access to those verifiable credentials to verifier coordinator s, as directed by the holder . In-browser retrieval of such stored credentials can enable web-based verifier coordinator s to integrate data from the holder without sharing that data with the verifier —the data is only ever present in the browser. Authorizing third-party remote access to holder storage is likely in-scope for this API, although we expect this to be defined using extensible mechanisms to support a variety of storage and authorization approaches.

The issuer and verifier storage solutions may or may not use secure data storage. Since all such storage interaction is moderated by the bespoke issuer and Storage Coordinators, any necessary integrations can simply be part of that bespoke customization. We expect different implementations to compete on the ease of integration into various back-end storage platforms.

A workflow service provides a way for coordinators to automate specific interactions for specific users. Each role ( holder , issuer , and verifier ) can run their own workflow service to create and manage exchanges that realize particular workflows. Administrators configure the workflow system to support particular flows. Then, when the business rules justify it, coordinators create exchanges at their workflow service and give access to those exchanges to any authorized party.

An administration service is an acknowledgement that each of the other components need a way to be configured and managed, without prescribing the interfaces or means of that configuration. Some components might use JSON files to drive a command line interface. Others might expose HTML pages. It is expected that different implementations will compete on the power, ease, and flexibility of their administration and therefore, configuration is largely out of scope for this specification. There are some places where some configuration mechanisms are provided, such as in Section 3.6.1 Create Workflow , where there was broad agreement to standardize some configuration parameters. As the market matures, other areas of configuration standardization might occur in future versions of this specification.

The APIs defined in this specification presume that they are attached to a specific instance with an associated configuration that has been put in place by a system administrator. When a client calls an endpoint on a particular instance , the instance uses the configuration and options provided by the client to execute the action.

For example, the /credentials/issue endpoint can be provided at the end of a longer URL such as /instances/12345/credentials/issue. In this case, it is the instance that is configured to know which cryptographic key to use for issuance, whether or not a status list is involved, the type of credential to issue, the credential format, and what additional options are possible on the endpoint.

Software clients that call a particular instance might not have the capability to configure an instance , or be aware of the setup that the administrator did on the instance other than the requisite details to make appropriate use of it. Administration endpoints for configuring instances could be provided by implementations but are not necessarily exposed as HTTP APIs; configuration can also be done through configuration files or graphical interfaces.

Note : A coordinator can use multiple service instances

A coordinator instance can have access to multiple service instances in order to support different use cases or a use case with complex flows. Runtime discovery of service instance configuration is not defined by this specification as services are expected to be known by the coordinator at the time of deployment.

Each coordinator or service instance is associated with a specific configuration that drives its behavior. This section contains how some of those configurations might be performed.

There are no restrictions put on the base URL for any particular instance . The URL paths used throughout this specification are shown as absolute paths and their base URL MAY be the host name of the server (e.g., website.example ), a subdomain (e.g., api.website.example, or a path within that domain (e.g., website.example/api ).

This API can be deployed in a variety of networking environments which might contain hostile actors. As a result, conforming service implementations require conforming service client implementations to utilize secure authorization technologies when performing certain types of requests. Each HTTP endpoint defined in this document specifies whether or not authorization is required when performing a request. With the exception of the class of forbidden authorization protocols discussed later in this section, this API is agnostic regarding authorization mechanism.

This API is meant to be generic and useful in many scenarios that require the issuance, possession, presentation, and/or verification of Verifiable Credentials. To this end, implementers are advised to consider the following classifications of use cases:

Public . A Public API is one that can be called with no authorization. Examples include an open witness or timestamp service (a trusted service that can digitally sign a message with a timestamp for an audit trail purpose), or an open retail coupon endpoint ("buy one, get one free"). Public verifiers might also exist as well, to act as an agnostic third party in a trust scenario.
Permissioned . Permissioned authorization requires the entity making the API call to, for example, have an access control token or a capability URL, or to invoke a capability from a mutually trusted source. These permissions grant access to the API, but make no assumptions about credential subjects, previous interactions, or the like. Permissioned access is particularly useful in service-to-service based workflows, where credential subjects are not directly involved.
Bound . Bound authorization involves scenarios where the API calls are tightly coupled, linked, or bound to another process, often out-of-band, that has authenticated the holder/subject of the API interaction. These use cases include, but are not limited to, issuance of subject-specific identity claims directly to the subject in question, or verification of credentials to qualify the holder for service at the verifier, for example. Examples of methods to bind activity on one channel to an API call include CHAPI (the Credential Handler API ), OIDC (OpenID Connect), and GNAP (the Grant Negotiation and Authorization Protocol). Developers implementing bound authorization will need to take steps to ensure the appropriate level of assurance is achieved in the flow to properly protect the binding.

The rest of this section gives examples of the authorization technologies that have been contemplated for use by conforming implementations. Other equivalent authorization technologies can be used. Implementers are cautioned against using non-standard or legacy authorization technologies.

Requests to this API MUST NOT utilize any authorization protocol that includes long-lived static credentials such as usernames and passwords or similar values in those requests. An example of such a forbidden protocol is HTTP Basic Authentication [ RFC7617 ].

If Authorization Capabilities (ZCAPs) are used for authorization, the administrator is expected to delegate a ZCAP with the appropriate format as defined in [ ZCAP ] and as needed for the use case. This includes appropriate values for the controller, invocation target, and allowed actions, among other important properties.

Example 1 : VCALM Delegated Capability

{
  "@context": [
    "https://w3id.org/zcap/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "urn:uuid:cdc77118-6bfa-11ec-aceb-10bf48838a41",
  "parentCapability": "urn:zcap:root:https%3A%2F%2Fvcalm-instances.example.com%2Fissuers%2Fb77c9b57-c321-4d14-902c-8f442a37707d%2Fworkflows%2Fa6513552-8e5a-4efa-b36e-1fb2a8e06822%2Fexchanges",
  "controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
  "invocationTarget": "https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822/exchanges",
  "expires": "2027-06-30T16:45:73Z",
  "allowedAction": [
    "write",
    "read"
  ],
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-06-30T16:45:73Z",
    "verificationMethod": "did:key:z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9#z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9",
    "proofPurpose": "capabilityDelegation",
    "capabilityChain": [
      "urn:zcap:root:https%3A%2F%2Fvcalm-instances.example.com%2Fissuers%2Fb77c9b57-c321-4d14-902c-8f442a37707d%2Fworkflows%2Fa6513552-8e5a-4efa-b36e-1fb2a8e06822%2Fexchanges"
    ],
    "proofValue": "z3t9BCQyF21MDVYmLKc9zbLreqx4wBtQnUsd5aqyoWS5FfhapRz7QjPNLcgKAornUVmJR4ZjbGpuxRFnffxX1ZjtF"
  }
}

The read action enables operations that do not create or update resources in the system to be performed on the provided path, or on any path containing the provided path as a prefix, as permitted by invocationTarget and allowedAction in the ZCAP. The write action enables operations that create and/or update resources in the system to be performed on the provided path, or on any path that contains the provided path as a prefix, as permitted by invocationTarget and allowedAction in the ZCAP. To enforce the principle of least privilege, implementers are expected to apply the following best practices:

Ensure that ZCAPs identify a specific URL that references resources via the invocationTarget property and the client that is authorized to access those resources via the controller property. This enables the ZCAP to be pinned to a particular client and server (along with its resources). Example invocationTarget value: https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822. Example controller value: did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG.
Refer to Section 3.1 Component Overview to determine which invocationTarget and allowedAction values to include in ZCAPs distributed to clients, based on the HTTP method (e.g., GET -> read, POST -> write ) and the expected caller of the API endpoint of interest.

Examples of valid delegated capability subsets are shown below:

{
  ...
  "controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
  "invocationTarget": "https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822",
  "allowedAction": [
    "write",
    "read"
  ],
  ...
}

{
  ...
  "controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
  "invocationTarget": "https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822/exchanges",
  "allowedAction": [
    "write",
    "read"
  ],
  ...
}

{
  ...
  "controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
  "invocationTarget": "https://vcalm-instances.example.com/issuers/b77c9b57-c321-4d14-902c-8f442a37707d/credentials/issue",
  "allowedAction": [
    "write"
  ],
  ...
}

If the OAuth 2.0 Authorization Framework [ RFC6749 ] is used for authorization, the access tokens used by clients are expected to be OAuth 2.0 Bearer Tokens [ RFC6750 ] or any other valid OAuth 2.0 token type. Any valid OAuth 2.0 grant type can be used to request the access tokens.

VCALM OAuth 2.0 Scope Syntax
scope = operation ":" path-absolute (defined in [ RFC3986 ]) operation = "read" / "write"

The read operation enables actions that do not create or update resources in the system to be performed on the provided path, or on any path containing the provided path as a prefix. The write operation enables actions that create and/or update resources in the system to be performed on the provided path, or on any path that contains the provided path as a prefix. To enforce the principle of least privilege, implementers are expected to apply the following best practices:

Ensure that access tokens expressed as JSON Web Tokens (JWT) include an aud (audience) claim that identifies a specific instance for which the access token applies, allowing the token to be pinned to a particular instance. For multi-tenant deployments, this is expected to include the component instance of interest. Example aud value: https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822.
Include the entire API path (excluding the domain and component instance, which are captured in aud ) in the scopes configured for the OAuth 2.0 issuer (see examples below).
Refer to Section 3.1 Component Overview to determine which scopes to include in access tokens distributed to clients, based on the HTTP method (e.g., GET -> read, POST -> write ) and the expected caller of the API endpoint of interest.

Examples of valid OAuth 2.0 scopes are shown below:

read:/ would allow a client to retrieve resources via any API on a particular instance (an access token with this scope is expected to be distributed to an administrator and the full instance ID would be included in the decoded JWT's aud claim).
write:/ would allow a client to create and modify resources via any API on a particular instance (an access token with this scope is expected to be distributed to an administrator and the full instance ID would be included in the decoded JWT's aud claim).
write:/exchanges would allow a client to create an exchange on a particular workflow instance (an access token with this scope is expected to be distributed to a coordinator and the full workflow instance ID would be included in the decoded JWT's aud claim).
read:/exchanges would allow a client to retrieve the state of an exchange originating from a particular workflow instance (an access token with this scope is expected to be distributed to a coordinator and the full workflow instance ID would be included in the decoded JWT's aud claim).
write:/credentials/issue would allow a client to access the API endpoint for credential issuance on a particular issuer instance (an access token with this scope is expected to be distributed to an issuer coordinator or a workflow service and the full issuer instance ID would be included in the decoded JWT's aud claim).

Broad OAuth 2.0 scopes such as read:/ and write:/ can lead to security vulnerabilities in multi-tenant environments, such as when multiple issuer coordinators might use different issuer instances hosted on the same issuer service . Implementers are advised to ensure that access tokens expressed as JSON Web Tokens include an aud (audience) claim that identifies a specific instance for which the access token applies, allowing the token to be pinned to a particular instance. It is advised that OAuth 2.0 scopes be kept as narrow as possible without making them overly burdensome to security administrators.

Some of the endpoints defined in the following sections accept an options object. All properties of the options object are OPTIONAL when configuring each instance, as these properties are intended to meet per-deployment needs that might vary. Thus, any given instance configuration MAY prohibit client use of some options properties in order to prevent clients from passing certain data to that instance. Likewise, an instance configuration MAY require that clients include some options properties.

Implementations MAY extend an options object with additional properties.

As extension properties are implementation specific, they ought not be mandatory. This is to maintain interoperability by avoiding clients needing to be modified to use a specific implementation.

When adding an extension options property, consider whether providing optionality to clients is necessary. If not, using instance configuration to vary API functionality might be a preferable approach.

Implementations MUST throw an error if an endpoint receives data, options, or option values that it does not understand or know how to process.

All entity bodies in requests and responses sent to or received from the API endpoints defined by this specification MUST be serialized as JSON and include the Content-Type header with a media type value of application/json.

This section is non-normative.

The OpenAPI descriptions in this specification represent verifiable credential and verifiable presentation request and response bodies using a minimal property table: @context and type. This keeps the API description focused on what VCALM defines — HTTP endpoints, request and response structure, options, workflows, exchanges, and related coordinator and service behavior — rather than repeating the full graph of a verifiable credential or verifiable presentation in every endpoint table.

The semantic content of credentials and presentations exchanged through these APIs is defined by the Verifiable Credentials ecosystem specifications that apply to a given deployment. VCALM interop testing is intended to exercise API behavior; data model conformance is out of scope for this specification and is covered by separate test suites.

OpenAPI uses separate schema names for the same sparse property table where the API distinguishes roles: Credential and Presentation for input documents (for example, credential in an issue request), and VerifiableCredential and VerifiablePresentation where a secured artifact is expected (for example, verifiableCredential in a response). The schemas share the same underlying document shape; the names signal API usage rather than different normative data model requirements.

Where this specification needs to express support for alternate serializations at the API boundary, it does so explicitly through EnvelopedVerifiableCredential, EnvelopedVerifiablePresentation, and negotiation properties such as acceptedEnvelopes and acceptedCryptosuites in verifiable presentation requests . See Section 3.4 Requesting a Presentation .

Implementers are encouraged to pay attention to the payload sizes of the Verifiable Credentials that their implementations process.

Presentations can bundle a large volume of credentials, which can result in a higher request size than anticipated by implementers. This raises the risk of interoperability issues.

A default maximum size of 10MB per verifiable credential is RECOMMENDED as an interoperability baseline, with the possibility of configuring a larger size if required. This also accommodates the 16MB size limit of most document-based database storage solutions.

By default, large binary values are expected to be linked to and a hash included (unless there is a privacy reason for not doing so).

This section contains the HTTP API endpoint definitions and implementation guidance that is to be followed when creating conforming implementations .

This section gives an overview of all endpoints in the VC-API by the component the endpoint is expected be callable from. If a component does not have a listing below it means the VC-API does not currently specify any endpoints for that component.

Below are all endpoints expected to be exposed by the issuer coordinator , along with the component that is expected to call the endpoint.

Below are all endpoints expected to be exposed by the issuer service , along with the component that is expected to call the endpoint.

Below are all endpoints expected to be exposed by the verifier coordinator , along with the component that is expected to call the endpoint.

Below are all endpoints expected to be exposed by the verifier service , along with the component that is expected to call the endpoint.

Below are all endpoints expected to be exposed by the holder coordinator , along with the component that is expected to call the endpoint.

Below are all endpoints expected to be exposed by the holder service , along with the component that is expected to call the endpoint.

Below are all endpoints expected to be exposed by the status service , along with the component that is expected to call the endpoint.

Below are all endpoints expected to be exposed by the Workflow Service, along with the component that is expected to call the endpoint.

The following APIs are defined for issuing a Verifiable Credential:

This endpoint is used to issue a verifiable credential .

Note : Issued credential media types

To issue credentials with a media type other than application/vc — such as application/mdoc, application/vc+sd-jwt, application/vcb;barcode-format=qr_code, or application/vcb;barcode-format=pdf417 — an EnvelopedVerifiableCredential can be returned in the response.

If a use case requires an issuer instance to attach multiple proofs to the provided credential, the instance MUST attach all of these proofs in response to a single call to the /credentials/issue endpoint.

If a provided credential already contains one or more proofs, the behavior is determined by the configuration of the issuer instance. An issuing instance SHOULD be configured to handle existing proofs in one of the following ways:

Proof Sets : Append new proofs to the list of existing proofs provided by the caller, first converting any existing single proof to a list if necessary. Here there is no binding to any existing proofs; the new proofs exist in parallel with those previously provided by the caller.
Proof Chains : Append new proofs to create or extend an existing proof chain. Here proofs are linked in a specific sequence, potentially using the previousProof property to establish the chain relationship.
Error Handling : Return an error if credential values that contain existing proof values are provided, when the instance is configured to only accept credentials without existing proofs.

The specific approach used depends on the configuration of the issuer instance and the intended use case for the verifiable credential.

An issuer service or a holder service might store an issued verifiable credential for an extended period of time. When this is done, it can be useful to delete such a verifiable credential ; for instance, an issuer might need to do so because of regulatory requirements such as the right to be forgotten . See Section ~~B.3 Deletion~~ #deletion for additional considerations related to the removal of verifiable credentials from systems.

The following APIs are defined for verifying a Verifiable Credential:

This endpoint is used to verify a verifiable credential .

Note : Verify credential media types

To verify credentials with a media type other than application/vc, such as application/mdoc, application/vc+sd-jwt, application/vcb;barcode-format=qr_code, or application/vcb;barcode-format=pdf417 — an EnvelopedVerifiableCredential can be provided in the request.

This endpoint is used to verify a verifiable presentation and, by default, all verifiable credentials contained within it.

The verification process includes:

Verifying the presentation's own proof (including domain and challenge validation)
Verifying each contained verifiable credential's proof, status, and validity period(s)
Checking that the holder in the presentation matches the verification method used in the presentation's proof

Business rule validation (such as verifying that credential subjects match the presentation holder, or authorization policies about who can present which credentials) is outside the scope of this verification endpoint and should be performed by the calling application.

The instance should create a challenge for use during verification, and track the number of times the challenge has been passed to verification endpoints as options.challenge.

When working with verifiable credentials , and decentralized identifier -based authentication, one party often needs to request data from another. This section describes the general format of those requests and provides a concrete verifiable presentation request format as well.

A verifiable presentation request is a request a verifier makes to a holder for a presentation . To make a request for one or more credentials wrapped in a verifiable presentation , a verifier constructs a JSON request describing one or more credentials that it wishes to receive from the holder . The general format for a request looks like the following:

Example 2 : The general form of a verifiable presentation request

{
  // one or more requests for verifiable credentials
  "query": [{
    "type": "QueryByExample",
    // query details specific to QueryByExample...
  }],
  // The target security domain, such as a website domain, to include in
  // the verifiable presentation
  "domain": "domain.example",
  // The random challenge string to include in the verifiable presentation
  "challenge": "f63cb0d2-760e-11f0-a2b1-67febb854a5f"
}

The query property serves as the main extension point mechanism for requests for data in the presentation. While this document defines a common query mechanism (see Section 3.4.2 Query By Example ), all query objects are of the following form:

query: A REQUIRED property that specifies the information requested by the verifier . The value MUST be one or more maps where each map MUST define a type property with an associated string value.
domain: An OPTIONAL string that a verifier provides to a holder during a presentation request . The holder checks to ensure that the data is associated with the domain, such as a website domain, that they are interacting with, and if it is, includes the data in a verifiable presentation . A domain is used to ensure that the holder limits their verifiable presentation to a specific verifier , protecting the verifier against replay attacks .
challenge: An OPTIONAL , unique string that is provided by a verifier to a holder during a specific presentation request . The holder includes this data in a verifiable presentation to the verifier , protecting the verifier against replay attacks .

The "query by example" credential query format is designed to enable developers to easily request the claims that they need from one or more verifiable credentials , to enable a particular business process. The query can also specify other information, such as one or more issuers that are trusted by the verifier .

The credentialQuery property in a QueryByExample query is a single object. Logical "AND" and "OR" operations for combining multiple queries are handled through the group property at the query level, as described in Section 3.4.5 Logical Operations in Queries . Multiple queries with the same group value are processed as "AND" operations, while queries with different or missing group values are processed as "OR" operations.

Example 3 : A Query By Example query

{
  "query": [{
    "type": "QueryByExample",
    "credentialQuery": {
      // (Optional) Reason for requesting this credential that
      // may be shown to a user by their software
      "reason": "We need to know if you are an alumni of this school.",
      // (Optional) An example of the credential being requested
      "example": {
        "@context": [
          "https://www.w3.org/ns/credentials/v2",
          "https://www.w3.org/ns/credentials/examples/v2"
        ],
        "type": "ExampleAlumniCredential",
        // (Optional) Select credential based on credential subject type
        "credentialSubject": {
          "type": "Alumni"
        }
      },
      // (Optional) Specify credentials from particular acceptedIssuers or
      // delegates of the authority
      "acceptedIssuers": [
        {
          "id": "did:web:authority.example"
        },
        "did:web:different-issuer.example"
      ]
    }
  }],
  "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
  "domain": "reunion.example"
}

The credentialQuery object supports the following properties:

Property	Description
reason	An OPTIONAL string that provides a human-readable explanation for why the credential is being requested. This MAY be displayed to the holder by their software.
example	An OPTIONAL object that provides an example of the credential being requested, including its `@context`, `type`, and optionally `credentialSubject` fields to indicate which claims are needed.
acceptedIssuers	An OPTIONAL array of items, or lists that contain items, that identify entities that the verifier recognizes and accepts as issuers of the verifiable credential . Each item MUST be either 1) a [ URL ] that identifies an issuer in the `issuer` property of the received verifiable credential , or 2) an object that contains an `id` property whose value is a [ URL ] that identifies an issuer in the `issuer` property of the received verifiable credential , or 3) an object that contains a `recognizedIn` property that is associated with an object with a `type` property that is set to `RecognizedEntityCredential` and an `id` property with a [ URL ] value that points to such a credential as defined in the Recognized Entities v1.0 specification; the list contains recognized issuers that are acceptable to the verifier . Valid example values include: `did:web:red-issuer.example` `https://blue-issuer.example/` `{"id": "did:web:green-issuer.example"}` `{"recognizedIn": {"id": "https://url.example/list.vc", "type": "RecognizedEntityCredential"}}`
acceptedCryptosuites	An OPTIONAL array specifying which cryptographic proof suites the verifier will accept. Each element SHOULD be an object with a `cryptosuite` property referencing a Data Integrity cryptosuite name or `Ed25519Signature2020` for legacy (for backwards compatibility, string values MAY also be used and are to be interpreted as the cryptosuite name). This enables the holder to select an appropriate proof format. This property MAY be used independently of `acceptedEnvelopes`, which is only applicable to enveloped credentials. Valid example values include: `[{"cryptosuite": "eddsa-rdfc-2022"}, {"cryptosuite": "ecdsa-rdfc-2019"}]` `[{"cryptosuite": "bbs-2023"}, {"cryptosuite": "ecdsa-sd-2023"}]`
acceptedEnvelopes	An OPTIONAL array specifying which envelope formats the verifier will accept. Each element SHOULD be an object with a `mediaType` property referencing the media type for the envelope (for backwards compatibility, string values MAY also be used and are to be interpreted as the media type). This enables the holder to provide credentials in formats other than the default Data Integrity format. This property MAY be used independently of `acceptedCryptosuites`, which is only applicable to JSON-LD credentials signed with an acceptable cryptosuite. Valid example values include: `[{"mediaType": "application/jwt"}]` `[{"mediaType": "application/vc+sd-jwt"}]`

A JSON Schema for a QueryByExample is provided in a separate file for integration into software systems.

The following example demonstrates a QueryByExample that specifies accepted cryptosuites and envelope formats, enabling the holder to choose an appropriate proof mechanism:

Example 4 : A Query By Example with acceptable cryptosuites and envelopes

{
  "query": [{
    "type": "QueryByExample",
    "credentialQuery": {
      "reason": "Please present your PermanentResidentCard to complete the verification process.",
      "example": {
        "@context": [
          "https://www.w3.org/ns/credentials/v2",
          "https://w3id.org/citizenship/v3"
        ],
        "type": ["PermanentResidentCard"],
        "credentialSubject": {
          "birthCountry": ""
        }
      },
      "acceptedCryptosuites": [
        {"cryptosuite": "eddsa-rdfc-2022"},
        {"cryptosuite": "ecdsa-rdfc-2019"},
        {"cryptosuite": "bbs-2023"},
        {"cryptosuite": "ecdsa-sd-2023"}
      ],
      "acceptedEnvelopes": [
        {"mediaType": "application/jwt"},
        {"mediaType": "application/vc+sd-jwt"}
      ]
    }
  }],
  "challenge": "9876fedc-ba98-7654-3210-fedcba987654",
  "domain": "immigration.example"
}

In the example above, the verifier indicates it will accept credentials secured with any of the listed cryptosuites. By including bbs-2023 and ecdsa-sd-2023, the verifier signals that selective disclosure proofs are acceptable, allowing the holder to reveal only the birthCountry field rather than the entire credential. The acceptedEnvelopes property indicates that JWT-based envelope formats are also acceptable.

Note : Selective disclosure using Query By Example

Any field included in a Query By Example is a required field. This means that when using a Query By Example to enable selective disclosure, a requester needs to be mindful not to include fields in their query that are not needed for their use case. Query By Example provides no way to indicate an "optional" field; consequently, it is up to the wallet that is responding to the query to ensure that its response does not reveal any information beyond what is being requested. Note: Some securing mechanisms for verifiable credentials do not permit selective disclosure; in these cases, unrequested information might have to be sent in order to send the requested information. Digital wallets are expected to inform users about what information will be shared. To request a field without any statement about an expected value, a requester can include the field in the request and leave the value as an empty string. For instance, if a requester needs a first name, they could include the optional " credentialSubject " object with a single field, "firstName": "". This would allow a wallet to respond with only the firstName of the requested credential with no expectation of any other field being included. _This does not prevent a wallet from oversharing by including additional fields in its response to the query._ To signal that selective disclosure cryptosuites are acceptable, verifiers SHOULD include cryptosuites such as bbs-2023 or ecdsa-sd-2023 in the acceptedCryptosuites array.

This section defines how a verifier can request that a holder perform Decentralized Identifier-based Authentication [ DID-CORE ]. In its simplest form, the authentication protocol is comprised of a challenge by the verifier and a response by a holder :

Example 5 : A DID Authentication request

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "example"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "example.com"

}

The DID Authentication request above specifies that the verifier would like the holder to demonstrate control over a DID by generating a digital signature over the provided challenge. The holder might respond by providing the following response:

Example 6 : A DID Authentication response

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "example.com",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }

}

The DID Authentication query format enables a verifier to request that a holder authenticate in specific ways. A DID Authentication query MUST be of the following form:

Property	Description
type	A REQUIRED string value that MUST be set to `DIDAuthentication`.
acceptedMethods	An optional array of objects expressing that the verifier would accept any DID Method listed. Each object in the array MUST contain a property called `method` with a value that is a DID Method name, and MAY contain other properties that are specific to the DID Method. Valid example values include: `[{"method": "key"}]` `[{"method": "key"}, {"method": "web"}]`
acceptedCryptosuites	An optional array of objects that conveys the cryptography suites among which the holder MUST choose when generating a cryptographic proof to be submitted to this verifier . Each object in the array MUST contain a property called `cryptosuite` with a value that is a Data Integrity cryptosuite name (or `Ed25519Signature2020` for legacy), and MAY contain other properties that are specific to the cryptosuite. Valid example values include: `[{"cryptosuite": "eddsa-rdfc-2022"}]` `[{"cryptosuite": "ecdsa-rdfc-2019"}, {"cryptosuite": "bbs-2023"}]`

The following example demonstrates that the verifier would like the holder to use the DID Web method and a data integrity ECDSA cryptography suite to authenticate over the established communication channel, such as the Credential Handler API (CHAPI):

Example 7 : A DID Authentication request using did:web and ecdsa-rdfc-2019

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "key"}],
    "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "example.com"

}

In the next example, the verifier would like the holder to use either the DID Key or DID Web method, with the standard EdDSA data integrity cryptography suite; optionally include a cryptographic proof that they are capable of performing a data integrity BBS proof; and authenticate over a different communication channel, in this case using a Verifiable Credential API HTTP endpoint.

Example 8 : A complex DID Authentication request

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "key"}, {"method": "web"}],
    "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}]
  }, {
    "type": "DIDAuthentication",
    "required": false,
    "acceptedMethods": [{"method": "key"}, {"method": "web"}],
    "acceptedCryptosuites": [{"cryptosuite": "bbs-2023"}]
  }],
  "challenge": "zLEwtBYgQVNR4tyeo",
  "domain": "didauth.example"

}

The DID Authentication response format enables a holder to provide the information requested by the verifier . A DID Authentication response MUST be a verifiable presentation of the following form:

Property	Description
type	A REQUIRED string value that MUST be set to `VerifiablePresentation`.
holder	A REQUIRED string value that MUST be set to a specific DID that is of the type that was requested in the DID Authentication query.
proof	A REQUIRED value that MUST be one or more specific digital proof types that were requested in the DID Authentication query. Each proof object MUST include the `domain` and `challenge` values that were provided in the DID Authentication query. Holder implementations MUST ensure that the `domain` specified by the verifier matches the domain used for the current channel of communication.

It is vital that a holder implementation check the domain provided by the verifier against the domain used for the current channel of communication. If a holder fails to do so, a dishonest verifier could then replay the message to a domain that is not their own. For example, a dishonest verifier operating from the evil.example domain could retrieve a challenge from your bank, specify a domain value of yourbank.example, and then replay your response to your bank to get access to your financial accounts. This attack is mitigated as long as implementations ensure that the appropriate domain is used when generating the verifiable presentation .

The example below demonstrates a simple DID Authentication response.

Example 9 : A DID Authentication response using did:key

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "example.com",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }

}

Issue 2

Authorization Capability queries and responses might not be standardized at this time. This example is provided to demonstrate that verifiable credentials and mDLs/mdocs are not the only type of credential that can be queried.

This query type would be included in a request to ask for Authorization Capabilities or "ZCAPs" in the Verifiable Presentation.

Example 10 : An Authorization Capability Request query

{
  "query": [{
    "type": "AuthorizationCapabilityQuery",
    "capabilityQuery": [{
      "referenceId": "a-memorable-name",
      "allowedAction": ["read", "write"],
      "controller": "did:example:1234",
      "invocationTarget": {
        "type": "urn:edv:documents"
      }
    }, {
      "referenceId": "another-memorable-name",
      "allowedAction": "sign",
      "controller": "did:example:1234",
      "invocationTarget": {
        "type": "Multikey",
        "proofPurpose": "assertionMethod"
      }
    }],
    challenge: "111112b24-63d9-11ea-b99f-4f66f3e4f81a"
  }]
}

In Verifiable Presentation Requests, the structuring and retrieval of information rely on the use of logical operations. "AND" and "OR" operations play crucial roles in defining the path to desired data.

At the top-most level of the request structure, different types of queries are expected to be processed as "AND" operations if each one's group property is set to the same value.

In this example, there are two queries with the group flag set to certification. This results in an "AND" operation, indicating that both of these conditions need to be met in order to fulfill the request.

Example 11 : Multiple credentials requested at once using top-level queries

{
  "query": [{
    "type": "QueryByExample",
    "group": "certification",
    // query details ...
  },
  // "AND"
  {
    "type": "DigitalCredentialQueryLanguage",
    "group": "certification",
    // query details ...
  }]

}

Within a specific query type, an "OR" operation can be applied, by either not specifying the group or providing group values that are different from one another.

Example 12 : Queries for alternate credentials where any match will succeed

{
  "query": [{
    "type": "QueryByExample",
    "group": "college-degree",
    // query details ...
  },
  // "OR"
  {
    "type": "DigitalCredentialQueryLanguage",
    "group": "job-experience",
    // query details ...
  }]

}

The following APIs are defined for presenting a Verifiable Credential:

The URL path value exchange-id is meaningful to the server but is opaque to the client. While some server implementations might use values that happen to be human-readable, clients are strongly advised to not assign semantics to any human-readable values.

Note : Presentation media types

An EnvelopedVerifiablePresentation can be returned in the response in order to create presentations with a media type other than application/vp, such as application/vp+jwt.

A workflow defines a particular set of steps for exchanging verifiable credentials between two parties across a trust boundary. Each step can involve the issuance, verification, transmission, and/or presentation of verifiable credentials. Workflows are designed to support both linear sequences of steps and more complex patterns including branching logic and repeated steps, enabling sophisticated interactions between the parties involved. Examples of VCALM workflows include, but are not limited to, the following:

Issuing an employee membership credential to an employee who has logged in to a coordinator website.
Issuing a vehicle title credential after receiving a presentation of a driver's license credential.
Verification of the presentation of a permanent resident credential.
Receipt of one or more newly-issued single-use proof of age credentials.

Workflow instances are expected to be created by administrators, for use with, for example, coordinator websites. A workflow instance is created by performing an HTTP POST to the workflow service's /workflows endpoint. The HTTP request body includes the configuration for the workflow instance. This includes, but is not limited to, information about the steps that define the workflow and any credential templates that will be used to issue verifiable credentials. The steps that define the workflow might also be templates, enabling additional flexibility. If a workflow involves the issuance of verifiable credentials, or the verification of presentations or credentials, then the workflow instance configuration can include authorization capabilities to use one or more issuer and/or verification services.

Once a workflow instance exists, authorization to create and query particular workflow interactions, called exchanges, can be given to coordinators.

An exchange represents a particular interaction based on a given workflow. The interaction will take place between an exchange client and the workflow service. Exchanges are expected to be transitory, only existing as long as the interaction takes to complete. The workflow service stores state information about each exchange, such as whether the exchange is pending, active, or complete, as well as the current step in the workflow, any workflow-specific variables and data, and any verifiable presentations and credentials received while the exchange executes. Implementers are free to use whatever variables they desire for their implementation in addition to the reserved variables defined in Section 3.6.3 Create Exchange . While there is no technical limitation on the number of steps in a workflow, implementers might want to enforce a default maximum number of steps to prevent bugs.

An issuer, verifier, or holder coordinator is responsible for creating exchanges. The coordinator creates an exchange by performing an HTTP POST to the /exchanges subpath of a chosen workflow, on the workflow service. The HTTP request body includes an expiration date and time for the exchange and any variables to be used to populate the workflow's templates for the particular exchange. The request body can also include configuration options to enable the exchange to be executed using additional protocols beyond this API. Once the exchange is created, an exchange URL that identifies the exchange and enables interaction with it is returned to the coordinator.

The exchange URL is given to the exchange client so that it can initiate the exchange. Note that while the exchange URL is given to the coordinator to then provide it to the exchange client, the actual exchange is performed between the exchange client and the workflow service; the coordinator is not involved after providing the exchange URL to the exchange client. To be clear: a coordinator can still use its own exchange client for any use case that requires it to execute the exchange itself.

Initiating the exchange does not require any authorization beyond the exchange URL. Depending on the workflow service implementation, exchange URLs can also be capability URLs (i.e., the URL is an unguessable secret such that only whomever is given the URL can initiate the exchange). If the workflow that the exchange is based on requires any additional authorization beyond the possession of the exchange URL, this is to be obtained during the exchange, not at its initiation.

The exchange URL can also be used by the coordinator to query the current state of the exchange as it progresses and to obtain information associated with the exchange that the workflow service has stored. Querying the exchange in this way requires additional authorization that the coordinator is expected to have and that the exchange client is not.

How the exchange URL is transmitted from a coordinator to an exchange client is out of scope for this specification. Known mechanisms for sharing the exchange URL with the client include the Credential Handler API (aka CHAPI), a QR code, or a universal link.

Exchanges are designed to be executable using other protocols in addition to this API exchange protocol; for example, an exchange could potentially be executable with any of the [ OPENID4VCI ], [ OPENID4VP ], [ DIDCOMM ], and exchange protocols. The protocols supported depend on the complexity of the workflow the exchange is based on, and the options provided by the coordinator when the exchange was created.

The exchange client is expected to initiate the exchange using a protocol that is compatible with how the client received the exchange URL. For example, the exchange URL could have been provided over CHAPI with a protocol identifier indicating that this API protocol ought to be used. Alternatively, the exchange URL could be included as the credential_issuer in an [ OPENID4VCI ] credential offer, or as the client_id of an [ OPENID4VP ] authorization request, indicating that [ OPENID4VCI ] or [ OPENID4VP ], respectively, ought to be used. This section focuses on how an exchange client uses this API to interact with the exchange; see Section 3.7.4 Interaction Protocols Response to see how to combine exchanges with other protocols such as [ OPENID4VCI ], [ OPENID4VP ], and [ DIDCOMM ].

Exchanges that are executed using this API protocol involve messages sent as request and response bodies over HTTP. Each message consists of a simple JSON object that includes zero or more of the following properties and values:

verifiablePresentation: A Verifiable Presentation or an array of Verifiable Presentations. This is used by either party in an exchange to provide information to the other party, either because the latter requested it or because the former is simply offering it.
verifiablePresentationRequest: A Verifiable Presentation Request. This is used by either party in an exchange to request information from the other party.
redirectUrl: A URL that can be used to continue an interaction at another location. One use case for this is to send the user of an exchange client back to a coordinator website after an exchange has completed.
referenceId: An optional identifier to correlate exchange messages. A server MAY include this value; if present, the client SHOULD include it in its next message. The value SHOULD be a urn:uuid value.

Custom properties and values might also be included, but are expected to trigger errors in implementations that do not recognize them.

To initiate an exchange using this API protocol, an exchange client performs an HTTP POST sending a JSON object as the request body. In the simplest case, when the client has no constraints of its own on the exchange — i.e., it has nothing to request from the other party — the JSON object is empty ( {} ). The workflow service responds with its own JSON object in the response body.

If that response object is empty, the exchange is complete and nothing is requested from nor offered to the exchange client. If the object includes verifiablePresentationRequest, then the exchange is not yet complete and some additional information is requested, as specified by the contents of the associated verifiable presentation request. If the object includes verifiablePresentation, then some information is offered, such as verifiable credentials issued to the holder operating the exchange client or verifiable credentials with information about the exchange server's operator based on the exchange client's request. If the object includes redirectUrl, the exchange is complete and the workflow service recommends that the client proceed to another place to continue the interaction in another form.

Many verifiable credential use cases can be implemented using these basic primitives. Either party to an exchange is capable of requesting verifiable presentations and of providing one or more verifiable credentials that might be necessary to establish trust and/or gain authorization capabilities, and either party is capable of presenting credentials that they hold or that they have issued. Specific workflows can be configured to expect specific presentations and credentials and to reject deviations from the expected flow of information. When a workflow service determines that a particular message is not acceptable, it raises an error by responding with a 4xx HTTP status message and a JSON object that expresses information about the error.

The exchange design approach is layered: it aims to provide a minimal communication message layer and a set of primitives that enable most use cases to be implemented via specific verifiable presentation requests and verifiable credentials at a layer above. See the appendices that follow for examples of workflows and exchanges that use specific verifiable presentation requests and verifiable credentials.

Note : Workflow Step and Credential Examples

Minimum viable examples of both step and credential templates, as well as a couple more complex workflow templates, can be found in the appendix Workflow Step and Template Examples .

A given interaction with an exchange is expected to be short-lived but other mechanisms can be used to enable longer or multi-stage interactions. Examples of other interaction mechanisms include SMS, email, web notifications, or phone calls. This approach simplifies digital wallet implementation and allows existing mechanisms to be reused without reinvention within this API. The Web or native platforms are expected to enable additional interactions via applications (such as Web browsers) or other platform features. For example, in asynchronous issuance, a holder requests a credential but waits for processing. In such cases, system components (such as an issuer coordinator) make use of mechanisms outside this API to notify the holder when their credential is ready for collection.

The following APIs are defined for using workflows and exchanges for credential use cases that require crossing trust boundaries:

In the workflows and exchanges APIs, a "local" ID refers to an ID that is local to a service instance. In other words, an exchangeId or workflowId refers to a fully qualified URL, while a localExchangeId or localWorkflowId refers to a specific element in the URL path.

Workflows can contain information about steps, credential templates, and authorization. In some cases, a workflow will also reference the reserved results variable at different points in its configuration (typically in credential templates). This variable holds data that the workflow service receives from clients throughout the course of an exchange. Here is a basic workflow configuration that contains a DID Authentication step and a credential delivery step:

A step that includes an issueRequests array containing one or more issue request objects. Each issue request object identifies a credential template to use, either by its identifier ( credentialTemplateId ) or by its index ( credentialTemplateIndex ) in the workflow's credentialTemplates array. An issue request object MAY also include a variables property to provide values to be used when evaluating the credential template. By default, the result of each issue request is included in the verifiable presentation that is sent to the exchange client in the same step. An issue request object MAY include an optional result property whose value MUST be either the name of a top-level variable in the exchange's variables object or a JSON pointer to any variable within the exchange's variables object, identifying where the result of the issue request is to be stored. This enables greater composition, as subsequent steps can reference the stored result, or the exchange can end and a party with access to the exchange state can obtain the result for use in another exchange or via some other mechanism.

Example 13 : A Basic Workflow

{
  "id": "9fd3bc6d-4a04-4b3d-a983-3482d0586626",
  "initialStep": "didAuthRequest",
  "steps": {
    "didAuthRequest": {
      "createChallenge": true,
      "verifiablePresentationRequest": {
        "query": {
          "type": "DIDAuthentication",
          "acceptedMethods": [
            {
              "method": "key"
            },
            {
              "method": "web"
            }
          ],
          "acceptedCryptosuites": [
            {
              "cryptosuite": "eddsa-rdfc-2022"
            },
            {
              "cryptosuite": "ed25519-2020"
            }
          ]
        },
        "domain": "https://issuer.example.com"
      },
      "nextStep": "credentialDelivery"
    },
    "credentialDelivery": {
      "issueRequests": [
        {
          "credentialTemplateId": "caffb919-053a-4bfa-beba-80567904f842",
          "variables": "sampleAchievementCredential"
        }
      ]
    }
  },
  "credentialTemplates": [
    {
      "id": "caffb919-053a-4bfa-beba-80567904f842",
      "type": "jsonata",
      "template": "{
        \"credential\": {
          \"@context\": [
            \"https://www.w3.org/ns/credentials/v2\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/extensions.json\"
          ],
          \"id\": sampleAchievementCredential.id,
          \"type\": [\"VerifiableCredential\", \"AchievementCredential\"],
          \"issuer\": {
            \"type\": [\"Profile\"],
            \"name\": \"Example Issuer\",
            \"image\": {
              \"type\": \"Image\",
              \"id\": \"https://issuer.example.com/logo.png\"
            }
          },
          \"awardedDate\": sampleAchievementCredential.awardedDate,
          \"validFrom\": sampleAchievementCredential.validFrom,
          \"name\": \"Sample Achievement\",
          \"credentialSubject\": {
            \"id\": results.didAuthRequest.verifiablePresentation.holder,
            \"type\": \"AchievementSubject\",
            \"name\": sampleAchievementCredential.credentialSubject.name,
            \"achievement\": {
              \"id\": sampleAchievementCredential.credentialSubject.achievement.id,
              \"type\": [\"Achievement\"],
              \"achievementType\": sampleAchievementCredential.credentialSubject.achievement.achievementType,
              \"name\": sampleAchievementCredential.credentialSubject.achievement.name,
              \"description\": sampleAchievementCredential.credentialSubject.achievement.description,
              \"alignment\": sampleAchievementCredential.credentialSubject.achievement.alignment
            }
          }
        }
      }"
    }
  ],
  "controller": "did:web:issuer.example.com"
}

A step MAY include a verifiablePresentation to explicitly express one or more verifiable presentation s to be used in that step. This presentation could be composed via other variables in an exchange and could be augmented with any additional verifiable credentials that might be issued during the step (per issueRequests ). This supports use cases where specific verifiable presentation versions are required, specific sub-types of verifiable presentations are required, or specific verifiable presentation contents are required, including previously out-of-band issued verifiable credentials that are to be delivered in the workflow step.

A step MAY include a redirectUrl to specify a URL to send to the client that can be used to continue an interaction at another location. One use case for this is to send the user of an exchange client back to a coordinator website after an exchange has completed. Another use case is to return an interaction URL that allows a server to implement custom business rules during a continuing interaction without requiring the client to navigate to a web browser. For example, a first exchange could request information from a user and then return an interaction URL via redirectUrl. The client (e.g., a digital wallet) can determine that it is an interaction URL (e.g., the URL uses ?iuv=1 ) and fetch it, causing the interaction server to run custom business logic and then return a protocol object with another exchange to continue the interaction.

Some workflows will need to reference custom variables in one or more of their steps. In this case, the coordinator will need to provide the appropriate value(s) for the variable(s) when it creates an exchange. Here is an example of a workflow configuration with a templated DID Authentication step (Notice the verifiablePresentationRequest and callbackUrl variables referenced in the didAuthRequest step):

Example 14 : A Templated Workflow

{
  "id": "9fd3bc6d-4a04-4b3d-a983-3482d0586626",
  "initialStep": "didAuthRequest",
  "steps": {
    "didAuthRequest": {
      "stepTemplate": {
        "type": "jsonata",
        "template": "{
          "createChallenge": true,
          "verifiablePresentationRequest": verifiablePresentationRequest,
          "callback": {
            "url": callbackUrl
          },
          "nextStep": "credentialDelivery"
        }"
      }
    },
    "credentialDelivery": {
      "issueRequests": [
        {
          "credentialTemplateId": "caffb919-053a-4bfa-beba-80567904f842",
          "variables": "sampleAchievementCredential"
        }
      ]
    }
  },
  "credentialTemplates": [
    {
      "id": "caffb919-053a-4bfa-beba-80567904f842",
      "type": "jsonata",
      "template": "{
        \"credential\": {
          \"@context\": [
            \"https://www.w3.org/ns/credentials/v2\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/extensions.json\"
          ],
          \"id\": sampleAchievementCredential.id,
          \"type\": [\"VerifiableCredential\", \"AchievementCredential\"],
          \"issuer\": {
            \"type\": [\"Profile\"],
            \"name\": \"Example Issuer\",
            \"image\": {
              \"type\": \"Image\",
              \"id\": \"https://issuer.example.com/logo.png\"
            }
          },
          \"awardedDate\": sampleAchievementCredential.awardedDate,
          \"validFrom\": sampleAchievementCredential.validFrom,
          \"name\": \"Sample Achievement\",
          \"credentialSubject\": {
            \"id\": results.didAuthRequest.verifiablePresentation.holder,
            \"type\": \"AchievementSubject\",
            \"name\": sampleAchievementCredential.credentialSubject.name,
            \"achievement\": {
              \"id\": sampleAchievementCredential.credentialSubject.achievement.id,
              \"type\": [\"Achievement\"],
              \"achievementType\": sampleAchievementCredential.credentialSubject.achievement.achievementType,
              \"name\": sampleAchievementCredential.credentialSubject.achievement.name,
              \"description\": sampleAchievementCredential.credentialSubject.achievement.description,
              \"alignment\": sampleAchievementCredential.credentialSubject.achievement.alignment
            }
          }
        }
      }"
    }
  ],
  "controller": "did:web:issuer.example.com"
}

For the openId options, specifically the values createAuthorizationRequest and authorizationRequest, the example below is provided to help developers understand what an [ OPENID4VP ] Authorization Request looks like:

Example 15 : An OID4VP Authorization Request

{
  "response_type": "vp_token",
  "presentation_definition": {
    "id": "f1bd224a-0fed-469a-b64a-dad7cf63fd98",
    "input_descriptors": [
      {
        "id": "77d50c71-95ef-442c-a372-f32e17634fab",
        "constraints": {
          "fields": [
            {
              "path": [
                "$['@context']"
              ],
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "const": "https://www.w3.org/ns/credentials/v2"
                }
              }
            },
            {
              "path": [
                "$['type']"
              ],
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "const": "VerifiableCredential"
                }
              }
            },
            {
              "path": [
                "$['credentialSubject']['name']"
              ],
              "filter": {
                "type": "string"
              }
            }
          ]
        },
        "purpose": "We require a name credential to display your name when you post messages."
      }
    ]
  },
  "response_mode": "direct_post",
  "client_metadata": {
    "vp_formats_supported": {
      "ldp_vc": {
        "proof_type_values": [
          "DataIntegrityProof",
          "Ed25519Signature2020"
        ],
        "cryptosuite_values": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022"
        ]
      }
    },
    "vp_formats": {
      "jwt_vp": {
        "alg": [
          "EdDSA",
          "Ed25519",
          "ES256",
          "ES384"
        ]
      },
      "jwt_vp_json": {
        "alg": [
          "EdDSA",
          "Ed25519",
          "ES256",
          "ES384"
        ]
      },
      "di_vp": {
        "proof_type": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022",
          "Ed25519Signature2020"
        ]
      },
      "ldp_vp": {
        "proof_type": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022",
          "Ed25519Signature2020"
        ]
      }
    }
  },
  "client_id": "https://some.example/workflows/z1A7ojitBF3pGpVzW17MgU7zm/exchanges/z1ACKwiBiXmuGjpKAdKMpBZXB/openid/client/authorization/response",
  "client_id_scheme": "redirect_uri",
  "response_uri": "https://some.example/workflows/z1A7ojitBF3pGpVzW17MgU7zm/exchanges/z1ACKwiBiXmuGjpKAdKMpBZXB/openid/client/authorization/response",
  "nonce": "z1ACKwiBiXmuGjpKAdKMpBZXB"
}

There is an expires property associated with exchanges, denoting the expiration date and time of the exchange. It is created using the /workflows/{localWorkflowId}/exchanges endpoint. This impacts the lifetime of challenges associated with such an exchange: if a challenge is bound to an exchange, that challenge ceases to be valid at the date referenced by the expires property of the exchange.

This endpoint provides a mechanism for a client to query an exchange for all of the protocols that it supports. A single exchange can support many protocols that are capable of achieving the goals of the exchange, such as the issuance of a verifiable credential into a digital wallet.

This endpoint also enables the website operator to delegate the authority to execute the exchange to a third party, such as a service provider, by delegating that trust through the HTTPS domain. For example, the website brand.example can delegate the operation of the exchange to a partner saas.example by using the saas.example domain in the list of protocols.

Figure 3 An example of a wallet using a protocol to a delegated exchange service.

This enables the client to depend on their trust in brand.example to delegate the operation of the exchange to a third party in the same way that a website links to resources from other domains to render a web page.

This endpoint MUST return the current verifiable presentation request to be returned by an exchange when accessed with an Accept header value of application/json. Processing this request SHOULD NOT advance the exchange to a new step nor perform any state-changing side effects, such as credential issuance. If there is no verifiable presentation request available for the exchange in the current step, the value of the verifiablePresentationRequest property returned by this endpoint MUST be an empty JSON object.

This might be a useful endpoint for integration with Digital Credentials . To make a [ digital-credentials ] request backed by the VCALM protocol, the coordinator MUST provide the interaction URL as the request data. Subsequently, the browser MUST fetch the interaction URL , retrieve the supported protocols, and perform an HTTP GET on the vcapi URL concatenated with /request.

This feature allows the browser to route their requests through the coordinator's origin (thereby anchoring the entire operation in said origin), to the delegate they have approved as a service provider. This convenience exists whether the request is made on the same device or forwarded for a cross-device request.

Finally, this endpoint operates without the need for signed requests, as it MAY rely on TLS and existing CA infrastructure, without a need for new certificates nor a need to incorporate those into the exchange protocol in an additive way. However, if we find that the [ digital-credentials ] or other supported protocols require signed requests or encrypted responses, then the request MAY be returned as a signed object referencing a public key that SHOULD be used to encrypt the response. Upon receipt of the (potentially encrypted) response, the coordinator could decrypt and deliver the response to the appropriate exchange or delegate decryption support to the exchange service altogether. The official decision on which interface VCALM prescribes for performing this functionality is in flux as the [ digital-credentials ] rules continue to evolve.

A server MAY include a referenceId property in an exchange message. If the client receives a referenceId, it SHOULD include the same referenceId in its next message to the server. This aids in debugging and ensures that potentially delayed or misordered messages are linked to the correct request. The value of referenceId SHOULD be a urn:uuid value.

The APIs in this specification enables unmediated (automated, machine-to-machine) or mediated (person in the loop) exchanges to be executed. These exchanges are initiated by a holder coordinator and responded to by any Coordinator that implements exchanges. The flows consist of the following steps:

The holder coordinator contacts the receiving Coordinator to request the initiation of a particular exchange.
The receiving Coordinator responds with a presentation request of some kind to authenticate and/or authorize the holder coordinator and provides the next hop in the exchange as a URL.
The holder coordinator responds to the receiving Coordinator with a Verifiable Presentation containing information that will satisfy the presentation request.
The receiving Coordinator responds with a Verifiable Presentation with the newly issued Verifiable Credentials or a further presentation request as expressed in step 2 above.

The holder coordinator MAY call the Coordinator's exchange discovery endpoint to determine if the holder coordinator supports the Coordinator's protocol requirements on a particular endpoint, before actually initiating the exchange.

A diagram of the steps outlined above is presented below:

Figure 4 A standard exchange between a holder and an issuer / verifier .

Note

The general exchange above can be performed in a way that is fully automated, mediated by a person, or in a hybrid fashion where portions are automated but interaction by a person is required at certain stages. The second step above is used to provide guidance on whether the next step is automated or requires an individual to intervene.

The following diagram illustrates an exchange where the holder coordinator initiates with a Verifiable Presentation Request, requiring credentials from the receiving Coordinator before proceeding:

Figure 5 A client-initiated exchange where the holder requests credentials from the issuer / verifier before proceeding.

The following diagram illustrates an exchange where the holder coordinator sends a counter-request after receiving the server's initial request:

Figure 6 A mid-exchange counter-request where the holder requests credentials from the issuer / verifier after receiving the server's initial request.

The following example demonstrates an exchange client initiating an exchange with a verifiablePresentationRequest that specifies which cryptographic proof formats and envelope types it will accept. If the credentialQuery property is not present, the exchange client will accept any credential(s) from the workflow service that match the specified formats.

Example 16 : Client-Initiated Exchange with Accepted Formats

{
  "verifiablePresentationRequest": {
    "query": [{
      "type": "QueryByExample",
      "credentialQuery": {
        "acceptedCryptosuites": [
          {"cryptosuite": "eddsa-rdfc-2022"},
          {"cryptosuite": "ecdsa-rdfc-2019"},
          {"cryptosuite": "bbs-2023"}
        ],
        "acceptedEnvelopes": [
          {"mediaType": "application/jwt"}
        ]
      }
    }]
  }
}

The following example demonstrates an exchange client requesting credentials from the workflow service before fulfilling any subsequent request. In this scenario, the exchange client requires proof that the server operator is a registered business before sharing personal information.

Example 17 : Client Requesting Server Credentials Before Proceeding

{
  "verifiablePresentationRequest": {
    "query": [{
      "type": "QueryByExample",
      "credentialQuery": {
        "reason": "Please present your BusinessRegistrationCredential to complete the verification process.",
        "example": {
          "@context": [
            "https://www.w3.org/ns/credentials/v2"
          ],
          "type": ["BusinessRegistrationCredential"]
        },
        "acceptedCryptosuites": [
          {"cryptosuite": "eddsa-rdfc-2022"}
        ]
      }
    }]
  }
}

It is useful for an implementation to communicate how to start interacting with it to another implementation. This bootstrapping process is called initiating an interaction , and communicates what protocols each implementation supports as well as how to start a particular interaction with the implementation.

Note : Interactions are application, use case, and protocol agnostic

While several interaction specifications reside in this document, the general approach is agnostic as to use case, application, and protocol. This approach can be used to pair two or more applications that desire to bootstrap into a particular protocol over any transmission medium — such as a web browser, QR Code (optical medium), or NFC (wireless medium) — where the protocol does not need to involve this API.

The sequence diagram below outlines an issuer generating an interaction URL , using a QR Code to share it with a holder , and proceeding with the vcapi protocol:

Figure 7 An issuer-initiated interaction using a QR Code

The sequence diagram below outlines a verifier generating an interaction URL , using a QR Code to share it with a holder , and proceeding with the vcapi protocol:

Figure 8 A verifier-initiated interaction using a QR Code

The sequence diagram below outlines a holder generating an interaction URL , using a QR Code to share it with a verifier , and proceeding with the inviteRequest protocol:

Figure 9 A holder-initiated interaction using a QR Code

The format of the interaction URL MUST conform to the syntax for the URL Standard and contain an iuv query parameter encoding the interaction URL version number, which MUST be 1 when using this version of this API. The interaction URL SHOULD be an HTTPS URL that contains an interaction-specific identifier. The URL SHOULD be opaque and require no URL syntax processing before it is fetched by the receiving system. An example of such a URL is shown below:

Example 18 : An interaction URL

https://app.example/interactions/z8n38Dp7a?iuv=1

Protocols that encode lengthy protocol-specific information into URLs suffer from limitations placed by software libraries on the maximum allowable length of a URL. At the time of writing, the suggested URL length limit is roughly 2,000 characters. Implementers SHOULD NOT put information that can be expressed in the response to a GET request for an interaction URL , defined in Section 3.7.4 Interaction Protocols Response , into the query parameters of the interaction URL .

Note : Interactions URL lives on Coordinators, not Workflow Services

A coordinator has the freedom to put the interaction URL at any location on its Web origin, because it is expected to be considered opaque by consuming software (except for the iuv query parameter). However, it is important that the interaction URL be hosted on a coordinator and NOT hosted at the workflow service. This enables the coordinator's Web origin (DNS domain name) to be used as a consistent trust signal by consumers and the application of business rules that might modulate actions.

An interaction QR Code MUST be an interaction URL expressed as a QR code according to ISO18004:2024: QR Code Bar Code Symbology Specification . To ensure broad interoperability, the length of the interaction URL SHOULD be as short as possible, SHOULD NOT exceed 400 alphanumeric characters, and MUST NOT exceed 4,296 alphanumeric characters. An example of an interaction QR code can be found below:

A square image filled with black and white dots that is encoding a interaction URL — Figure 10 An interaction QR code for `https://app.example/interactions/z8n38Dp7a?iuv=1`

It can be useful to invoke an application that is capable of processing an interaction URL . This section defines an interaction: protocol scheme format (for native apps) and a web+interaction: protocol scheme format (for web apps) for this purpose. The format of the protocol scheme MUST conform to the following syntax:

The Interaction Protocol Scheme
scheme = ("interaction:" / "web+interaction:") interaction-url interaction-url = URL

The interaction-url is any URL that conforms to the URL Standard and where retrieving the resource at the URL results in an interaction protocols response .

Example 19 : An example of a native interaction scheme URL

interaction:https://app.example/interactions/z8n38Dp7a?iuv=1

Example 20 : An example of a web interaction scheme URL

web+interaction:https://app.example/interactions/z8n38Dp7a?iuv=1

Performing a retrieval of the interaction URL results in instructions on how to start an interaction with the remote system.

When the interaction URL is fetched using an Accept header value of application/json, a single JSON object containing a protocols map MUST be returned where each key is a protocol identifier and each value is a URL that can be used to initiate the interaction. For example, performing an HTTP GET on the https://app.example/interactions/z8n38Dp7a?iuv=1 interaction URL might result in either of the following responses:

Example 21 : A list of protocols supported for a given interaction, with inviteRequest being generated by the Workflow Service in use.

{
  "protocols": {
    "inviteRequest": "https://saas.example/workflows/123/exchanges/987/invite-request/response",
    "vcapi": "https://saas.example/workflows/123/exchanges/987",
    "oid4vp-1.0": "openid4vp://?client_id=https%3A%2F%2Fapp.example%2Fworkflows%2F123%2Fexchanges%2F987%2Fopenid%2Fclient%2Fauthorization%2Fresponse&request_uri=https%3A%2F%2Fapp.example%2Fworkflows%2F123%2Fexchanges%2F987%2Fopenid%2Fclient%2Fauthorization%2Frequest'"
  }
}

Example 22 : The degenerate case where the list of protocols only includes the inviteRequest option.

{
  "protocols": {
    "inviteRequest": "https://saas.example/interactions/123/invite-request/response"
  }
}

The protocol response enables protocol execution to be delegated to third-party service providers through the HTTPS domain trust model, similar to the delegation mechanism described in the Get Exchange Protocols section. For example, the website app.example can delegate the operation of the exchange to a partner saas.example by including the saas.example domain in the list of protocols.

When the interaction URL is fetched using any unrecognized Accept header value, a text/html document MUST be returned with directions instructing a human being to use specific software that understands how to process interaction URLs .

Below is a table of interaction protocols that are supported today. There is broad interest in extracting this table into a separate document as a dependency of this specification. The reasoning behind this interest is that the idea of a generic, extensible, reference of credential management protocols has a natural appeal across various communities and use cases. In the event that this migration occurs, implementers are expected to use that reference instead of this table for protocol usage. In the event that there is a conflict between the table below and information in the new reference, implementers ought to note versioning differences of this specification and proceed with caution.

Property	Usage
`interact`	The `interact` interaction protocol is used to redirect a wallet to a different interaction URL, where the exchange will continue. This protocol can be used by exchanges as a delegation mechanism. The value of this entry should be an interaction URL. More details can be found in Section 3.7.1 Interaction URL Format .
`inviteRequest`	The `inviteRequest` interaction protocol is used by a local system to signal to the remote system that it would like an invitation to a remote system. The value of this entry should be the URL of a website where an individual can engage in a use-case-specific interaction. More details can be found in Section 3.7.5 `inviteRequest` Interaction Protocol .
`vcapi`	The `vcapi` interaction protocol is used to initiate a specific exchange as described in Section 3.6.6 Participate in an Exchange . The value of this entry should be the fully-qualified URL used as the ID for the exchange. More details can be found in Section 3.7.6 `vcapi` Interaction Protocol .
`didcomm`	The `didcomm` interaction protocol is used to initiate a credential issuance or presentation flow in accordance with the latest version of [ DIDCOMM ]. The value of this entry should be the Out-of-Band (OOB) Invitation URL for the exchange. More details can be found in DIDComm Messaging .
`oid4vci-1.0`	The `oid4vci-1.0` interaction protocol is used to initiate a credential issuance flow in accordance with version 1.0 of [ OPENID4VCI ]. The value of this entry should be the Authorization Endpoint, against which the wallet should perform an Authorization Request for the exchange. More details can be found in OpenID for Verifiable Credential Issuance 1.0 . Implementers are advised to understand the drift that has occurred with this specification and the impact that this has made on the semantics of this property. Specifically, due to the material differences between popular draft versions and the stable 1.0 version, it is difficult for a wallet to know how to process an inbound request without coordination in advance. As a result of this, implementers are advised to use the versioned variant of this property as described in the protocol versioning note below.
`oid4vp-1.0`	The `oid4vp-1.0` interaction protocol is used to initiate a credential presentation flow in accordance with version 1.0 of [ OPENID4VP ]. The value of this entry should be the Authorization Endpoint, against which the wallet should perform an Authorization Request for the exchange. More details can be found in OpenID for Verifiable Presentations 1.0 . Implementers are advised to understand the drift that has occurred with this specification and the impact that this has made on the semantics of this property. Specifically, due to the material differences between popular draft versions and the stable 1.0 version, it is difficult for a wallet to know how to process an inbound request without coordination in advance. As a result of this, implementers are advised to use the versioned variant of this property as described in the protocol versioning note below.
`OID4VCI`	A deprecated and unversioned variant of the `oid4vci` versioned interaction protocol properties that is indefinitely retained here for backwards compatibility. Implementers are advised to upgrade to one or more of the versioned variants of the `oid4vci` properties, only using the deprecated `OID4VCI` property for a reasonable transition period during which they interpret `OID4VCI` from peer systems as an unversioned or multiversion variant.
`OID4VP`	A deprecated and unversioned variant of the `oid4vp` versioned interaction protocol properties that is indefinitely retained here for backwards compatibility. Implementers are advised to upgrade to one or more of the versioned variants of the `oid4vp` properties, only using the deprecated `OID4VP` property for a reasonable transition period during which they interpret `OID4VP` from peer systems as an unversioned or multiversion variant.

Note : Versioning exchange protocols

For protocols where version ambiguity could cause interoperability issues, implementers might consider adding information to the protocol properties. One way to do this would be to use the pattern " PROTOCOL - MAJOR. MINOR ". For example, instead of oid4vp, they ought to use oid4vp-draft28 or oid4vp-1.0.

Note : Mapping to exchange URLs

Some coordinator implementations will implement the protocols endpoint as a pass through to a protocols endpoint for an exchange instance. For example, a GET on https://app.example/interactions/z8n38Dp7a?iuv=1 will result in a pass-through GET on https://app.example/workflows/123/exchanges/987/protocols, which would return the response above. Implementing interaction URLs in this way can provide an easier implementation path.

The inviteRequest interaction protocol is used by a local system to signal to the remote system that it would like an invitation to a remote system via a specific URL, such as a website where an individual can engage in a use-case specific interaction. If the inviteRequest interaction protocol is selected, the local system sends data using an HTTP POST to instruct the remote system where to send the individual. A couple examples of the POST data are shown below. These examples intend to highlight that this specification does not state any requirements as to how the "url" field is formatted, but does recommend that an implementer of this interaction mechanism make use of a unique ID:

Example 23 : A response to an invitation request, for checking out at a store

{
  "url": "https://website.example/checkout/8372974",
  "purpose": "Checkout at ShopCo",
  "referenceId": "417bcaf2-14d9-11f0-99d7-9f094678517b"
}

Example 24 : A response to an invitation request, to fill out an online form

{
  "url": "https://website.example/forms/7864165",
  "purpose": "Fill out online form",
  "referenceId": "d4a6e5b8-1715-4654-8e47-e68b311756d1"
}

The vcapi interaction protocol is used to initiate a specific exchange as described in Section 3.6.6 Participate in an Exchange .

Example 25 : A VC-API interaction protocol request

{
  "verifiablePresentationRequest": {
    "query": [{
      "type": "QueryByExample",
      "credentialQuery": {
        "reason": "Please provide your student ID.",
        "example": {
          "@context": [
            "https://www.w3.org/ns/credentials/v2",
            "https://www.w3.org/ns/credentials/examples/v2",
          ],
          "type": "StudentIdCredential",
          "credentialSubject": {
            "studentId": ""
          },
        },
        "acceptedIssuers": [{
          "id": "did:web:university.example"
        }]
      }
    }],
    "challenge": "5e34826e-14da-11f0-98a5-8b1c0a196728",
    "domain": "university.example"
  }
}

When an implementation detects an anomaly while processing a document, a ProblemDetails object can be used to report the issue to other software systems. The interfaces for these objects follow [ RFC9457 ] to encode the data. A ProblemDetails map consists of the following properties:

type: The type key MUST be present and its value MUST be a URL identifying the type of problem.
title: The title key SHOULD provide a short but specific human-readable string for the problem.
detail: The detail key SHOULD provide a longer human-readable string for the problem.

Leveraging keys such as detail, and instance is encouraged, to provide more contextual feedback about the error, while being conscious of security concerns and hence not disclosing sensitive information.

The following problem description types are defined by this specification:

https://www.w3.org/TR/vcalm#UNKNOWN_OPTION_PROVIDED: An option that is unknown to the implementation was provided to the API call.

Further lists of ProblemDetails that might be reported by implementations can be found in the following specifications:

Section 7.2: Problem Details in the Verifiable Credentials Data Model v2.0 specification.
Section 4.7: Processing Errors in the Verifiable Credential Data Integrity 1.0 specification.
Section 3.5: Processing Errors in the Bitstring Status List v1.0 specification.

Example 26 : An example of a ProblemDetails object

{
  "type": "https://www.w3.org/TR/vc-data-model#CRYPTOGRAPHIC_SECURITY_ERROR",
  "status": 400,
  "title": "CRYPTOGRAPHIC_SECURITY_ERROR",
  "detail": "The cryptographic security mechanism couldn't be verified. This is likely due to a malformed proof or an invalid verificationMethod."

}

Issue 3

The example type URLs above will work in the future after VCDM v2.0 becomes a global standard. To ensure the error links to the appropriate location, you can replace the base URL of https://www.w3.org/TR/vc-data-model with www.w3.org/TR/vc-data-model-2.0 for the time being.

Implementers are strongly advised to sanitize all server errors in production environments, as not doing so can lead to information disclosure.

It is recommended to avoid raising errors while performing verification, and instead gather ProblemDetails objects to include in the verification results.

This specification defines a distinction between a verification error and a verification warning. Errors are ProblemDetails relating to cryptography, data model, and malformed context and are unrecoverable. Warnings are ProblemDetails relating to status and validity periods and might be recoverable or leave the subsequent action to the discretion of the application.

If an error is included, the verified property of the VerificationResponse object MUST be set to false ; if no errors are included, it MUST be set to true.

Example 27 : An example verification response containing warnings and errors.

{
  "verified": false,
  "document": verifiableCredential,
  "mediaType": "application/vc",
  "controller": issuer,
  "controllerDocument": didDocument,
  "warnings": [ProblemDetails],
  "errors": [ProblemDetails]
}

VCALM v1.0

A Verifiable Credential API for Lifecycle Management

Abstract

Status of This Document

1. Introduction

1.1 Design Goals and Rationale

HTTP API Design Guidelines

1.2 Architecture Overview

1.3 Conformance

1.4 Terminology

2. Architecture

2.1 Coordinators

2.2 Services

2.3 Instances

2.4 Configurations

Base URL

Authorization

Forbidden Authorization

Authorization Capabilities

Allow a client controller to update or retrieve the configuration of a particular workflow instance (a ZCAP with this subset is expected to be distributed to an administrator)

Allow a client controller to create exchanges or retrieve the state of any exchange from a particular workflow instance (a ZCAP with this subset is expected to be distributed to a coordinator)

Allow a client controller to access the API endpoint for credential issuance on the issuer instance identified in the ZCAP (a ZCAP with this subset is expected to be distributed to an issuer coordinator or a workflow service)

OAuth 2.0

Options

Content Serialization

Credential and Presentation Objects in API Descriptions

Payload Sizes

3. HTTP API

3.1 Component Overview

Issuer Coordinator

Issuer Service

Verifier Coordinator

Verifier Service

Holder Coordinator

Holder Service

Status Service

Workflow Service

3.2 Issuing

3.2.1 Issue Credential

3.2.2 Get a Specific Credential

3.2.3 Delete a Specific Credential

3.3 Verifying

3.3.1 Verify Credential

3.3.2 Verify Presentation

3.3.3 Create Challenge

3.4 Requesting a Presentation

3.4.1 Verifiable Presentation Request

3.4.2 Query By Example

3.4.3 DID Authentication

3.4.3.1 The DID Authentication Query Format

3.4.3.2 The DID Authentication Response Format

3.4.4 Authorization Capability Request

3.4.5 Logical Operations in Queries

3.4.5.1 Top-Level Queries ("AND" Operation)

3.4.5.2 Nested Queries ("OR" Operation)

3.5 Presenting

3.5.1 Derive Credential

3.5.2 Create Presentation

3.5.3 Get Presentations

3.5.4 Get a Specific Presentation

3.5.5 Delete a Specific Presentation

3.6 Workflows and Exchanges

3.6.1 Create Workflow

3.6.2 Get Workflow Configuration

3.6.3 Create Exchange

3.6.4 Get Exchange Protocols

3.6.5 Get Current Exchange VPR

3.6.6 Participate in an Exchange

3.6.7 Get Exchange State

3.6.8 Exchange Step Callbacks

3.6.9 Exchange Examples

3.7 Initiating Interactions

3.7.1 Interaction URL Format

3.7.2 Interaction QR Code Format

3.7.3 Interaction Scheme Format

3.7.4 Interaction Protocols Response

3.7.5 inviteRequest Interaction Protocol

3.7.6 vcapi Interaction Protocol

3.8 Error Handling

3.8.1 Verification Errors vs. Warnings

3.7.5 `inviteRequest` Interaction Protocol

3.7.6 `vcapi` Interaction Protocol