VCALM v0.9

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 the OAuth 2.0 Authorization Framework [ RFC6749 ] is utilized for authorization, the access tokens utilized by clients MAY be OAuth 2.0 Bearer Tokens [ RFC6750 ] or any other valid OAuth 2.0 token type. Any valid OAuth 2.0 grant type MAY be used to request the access tokens. However, OAuth 2.0 MUST be implemented in the following way:

OAuth2 tokens for this purpose have an audience of the particular issuer instance, e.g., origin/issuers/zc612332f3.

The scopes are generalized to read/write actions on particular endpoints, as follows:

read:/ would allow reading on any API on a particular instance.
write:/ would allow writing on any API on a particular instance.

write:/credentials/issue would only allow writing to that particular API.

Other authorization mechanisms that support delegation might be defined in the future.

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.

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.

The status service provides three primary operations for managing status lists:

Create a list : Create a new status list credential that can be used to track the status of multiple verifiable credentials .
Get a list : Retrieve a publicly accessible status list credential for verification purposes.
Set a status : Update the status of a specific verifiable credential within a status list.

Note : Non-normative status list operations

The status list operations described in this specification (create list, get list, and set status) are non-normative and represent a recommended implementation approach. Status list creation and management might depend on various factors not accounted for in this specification, such as the following:

Business requirements and policies specific to the issuer or use case
Performance considerations, such as list size, update frequency, and caching strategies
Infrastructure constraints, including storage capacity and hosting capabilities
Regulatory or compliance requirements that might affect how status information is managed
Integration with existing credential management systems or workflows

Implementers are free to design their status list management systems according to their specific needs, as long as the resulting status information can be verified according to the status mechanism specification in use (e.g., [ VC-BITSTRING-STATUS-LIST ]).

To maximize privacy, verifiers are encouraged to obtain status information from holders rather than directly querying the status service. When a holder presents a verifiable credential , they are encouraged to include the corresponding status list credential or sufficient status information to enable verification without requiring the verifier to contact the issuer . This approach prevents correlation of status checks with specific verifiers or verifiable credentials .

This endpoint is used to create a new status list credential that can be used to track the status of verifiable credentials . A status list is itself a verifiable credential that contains status information for multiple credentials, enabling privacy-preserving status checks. The status list credential is returned in the response and can be made publicly accessible for verification purposes.

For consistency in verification processes, the status list credential typically uses the same securing mechanism (proof type and cryptographic suite) as the verifiable credentials it will be linked to. This allows verifiers to verify both the credentials and their associated status lists using the same verification methods.

For specific mechanisms by which to manage verifiable credential statuses, implementers are encouraged to refer to well-known external specifications, such as the [ VC-BITSTRING-STATUS-LIST ] specification, which provides a normative example of how to implement status list credentials.

This endpoint retrieves a publicly accessible status list credential. This endpoint is typically publicly accessible without authentication to enable verifiers and holders to retrieve status information.

The endpoint returns the status list credential in an appropriate format based on the media type requested or the default format configured for the service. The response is typically either a VerifiableCredential or an EnvelopedVerifiableCredential, consistent with the format used by the verifiable credentials that reference this status list. This allows verifiers to process the status list using the same mechanisms they use for verifying the associated credentials.

Note : Privacy-preserving status retrieval

For privacy-preserving status mechanisms, verifiers are encouraged to obtain status information from holders rather than directly querying this endpoint. When a holder presents a verifiable credential that includes status information (such as a credentialStatus property), the holder is encouraged to also provide the corresponding status list credential or sufficient status information to enable verification. This approach prevents the issuer from correlating status checks with specific verifiers or verifiable credentials , thereby preserving privacy.

When a verifier needs to check the status of a verifiable credential , the recommended flow is as follows:

The verifier requests a verifiable presentation from the holder .
The holder includes the verifiable credential along with the corresponding status list credential or status information in the presentation.
The verifier verifies the status using the information provided by the holder , without needing to directly contact the issuer .

This endpoint might also be useful for holders who need to retrieve status list credentials to include in presentations, or for cases where direct issuer contact is acceptable from a privacy perspective.

This endpoint is used to update the status of an issued verifiable credential within a status list. When a credential's status needs to be changed (e.g., revoked or suspended), this endpoint updates the corresponding entry in the status list credential.

The request typically specifies the credential to update, the status list entry information (including the status list credential identifier and the index within that list), and the new status value. The status service updates the status list credential accordingly.

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

Example 2 : 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.",
      // (Mandatory) 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 a particular authority or
      // delegate of the authority
      "authority": [{
        "issuer": "did:web:authority.example"
      }]
    }]
  }],
  "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
  "domain": "reunion.example"
}

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 3 : 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 4 : 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"
  }

}

Issue 2

The DID Authentication examples shown in this document use a new proof type called DataIntegrityProof which is currently under development in the W3C Verifiable Credentials Working Group .

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 cryptosuite name, 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 5 : 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 6 : 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 7 : 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 3

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 8 : 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 9 : 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 10 : 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.

Discovery is an optional call for the holder coordinator to ensure the holder coordinator can support the exchange protocol requirements before calling the endpoint. Coordinators SHOULD support the exchange discovery endpoint.

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 VC API 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 OID4VCI, OID4VP, 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 OID4VCI credential offer, or as the "client_id" of an OID4VP authorization request, indicating that OID4VCI or OID4VP, respectively, ought to be used. This section focuses on how an exchange client uses this API to interact with the exchange; see Appendix TBD to see how to combine exchanges with other protocols such as OID4VCI, OID4VP, 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:

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.
verifiablePresentation: A Verifiable Presentation. 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.

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.

These examples will be added later.

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:

Example 11 : 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"
}

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 12 : 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 OID4VP Authorization Request looks like:

Example 13 : 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.

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.

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 5 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 6 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 7 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 14 : 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.3 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 8 An interaction QR code for `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 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 15 : 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": "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 16 : 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, a text/html document MUST be returned with directions instructing a human being to use specific software that understands how to process interaction URLs.

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 17 : 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 18 : 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.5 Participate in an Exchange .

Example 19 : 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": ""
          },
        },
        "trustedIssuer": [{
          "issuer": "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 20 : 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 4

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 21 : An example verification response containing warnings and errors.

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

VCALM v0.9

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

OAuth 2.0

Options

Content Serialization

Payload Sizes

3. HTTP API

3.1 Component Overview

3.1.1 Issuer Coordinator

3.1.2 Issuer Service

3.1.3 Verifier Cooirdinator

3.1.4 Verifier Service

3.1.5 Holder Coordinator

3.1.6 Holder Service

3.1.7 Status Service

3.1.7.1 Create Status List

3.1.7.2 Get Status List

3.1.7.3 Update Status

3.1.8 Workflow Service

3.2 Issuing

3.2.1 Issue Credential

3.2.2 Get a Specific Credential

3.2.3 Update Status

3.2.4 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 Exchange Discovery

3.5.4 Get Presentations

3.5.5 Get 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 Participate in an Exchange

3.6.6 Get Exchange State

3.6.7 Exchange Step Callbacks

3.6.8 Exchange Examples

3.7 Initiating Interactions

3.7.1 Interaction URL Format

3.7.2 Interaction QR Code Format

3.7.3 Interaction Protocols Response

3.7.4 inviteRequest Interaction Protocol

3.7.5 vcapi Interaction Protocol

3.8 Error Handling

3.8.1 Verification Errors vs. Warnings

A. Privacy Considerations

A.1 Delegation

A.2 "Phoning Home" Considered Harmful

3.7.4 `inviteRequest` Interaction Protocol

3.7.5 `vcapi` Interaction Protocol