Verifiable Credentials API v0.7

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.

This section is non-normative.

The Verifiable Credentials specification [VC-DATA-MODEL-2.0] provides a data model and serialization to express digital credentials in a way that is cryptographically secure, privacy respecting, and machine-verifiable. This specification provides a set of HTTP Application Programming Interfaces (HTTP APIs) and protocols for issuing, verifying, presenting, and managing Verifiable Credentials.

When managing verifiable credentials, there are two general types of APIs that are contemplated. The first type of APIs are designed to be used within a single security domain. The second type of APIs can be used to communicate across different security domains. This specification defines both types of APIs.

The APIs that are designed to be used within a single security domain are used by systems that are operating on behalf of a single role such as an Issuer, Verifier, or Holder. One benefit of these APIs for the Verifiable Credentials ecosystem is that they define a useful, common, and vetted modular architecture for managing Verifiable Credentials. For example, this approach helps software architects integrate with common components and speak a common language when implementing systems that issue verifiable credentials. Knowing that a particular architecture has been vetted is also beneficial for architects that do not specialize in verifiable credentials. Documented architectures and APIs increase market competition and reduce vendor lock-in and switching costs.

The APIs that are designed to operate across multiple security domains are used by systems that are communicating between two different roles in a verifiable credential interaction, such as an API that is used to communicate presentations between a Holder and a Verifier. In order to achieve protocol interoperability in verifiable credentials interactions, it is vital that these APIs be standardized. The additional benefits of documenting these APIs are the same for documenting the single-security-domain APIs: common, vetted architecture and APIs, increased market competition, and reduced vendor lock-in and switching costs.

This specification contains the following sections that software architects and implementers might find useful:

1.1 Design Goals and Rationale specifies the high level design goals that drove the formulation of this specification.
1.2 Architecture Overview highlights the different roles and components that are contemplated by the architecture.
2. Terminology defines specific terms that are used throughout the document.
3.2 Authorization elaborates upon the various forms of authorization that can be used with the API.
3.8 Issuing describes the APIs for issuing verifiable credentials as well as updating their status.
3.9 Verifying specifies the APIs for verifying both verifiable credentials and verifiable presentations.
3.10 Presenting defines APIs for generating and deriving verifiable presentations within a trust domain, as well as exchanging verifiable presentations across trust domains.
Finally, Appendix A. Privacy Considerations, and B. Security Considerations are provided to highlight factors that implementers might consider when building systems that utilize the APIs defined by this specification.

This section is non-normative.

The Verifiable Credentials API is optimized towards the following design goals:

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.

A RESTful API approach was used as a basis for the specification. Some endpoints use what is referred to as the 'controller' resource naming style. JSON Schema: A Media Type for Describing JSON Documents is used to define the acceptable inputs to the APIs.

This section is non-normative.

The Verifiable Credentials Data Model defines three fundamental roles, the Issuer, the Verifier, and the Holder.

Diagram showing the verifiable credential roles of Issuer, Holder, and Verifier — Figure 1 The roles defined by the Verifiable Credentials Data Model specification.

Actors fulfilling each of these roles may use a number of software or service components to realize the VC API for exchanging Verifiable Credentials.

Each role associates with a role-specific Coordinator, Service, and Admin as well as their own dedicated Storage Service. In addition, the Issuer may also manage a Status Service for revocable credentials issued by the Issuer.

VC API Components of Coordinators, Services, and Admin for Issuers, Verifiers, and Holders — Figure 2 VC API Components. Arrows indicate initiation of flows.

Any given VC API implementation may choose to combine any or all of these components into a single functional application. The boundaries and interfaces between these components are defined in this specification to ensure interoperability and substitutability across the Verifiable Credential conformant ecosystem.

In addition to aggregating components into a single app, implementers may choose to operationalize any given role over any number active instances of deployed software. For example, a browser-based Holder Coordinator should be considered as an amalgam of a web browser, various code running in that browser, one or more web servers (in the case of cross-origin AJAX or remote embedded content), and the code running on that server. Each of those elements runs as different software packages in different configurations, each executing just part of the overall functionality of the component. For the sake of the VC API, each component satisfies all of its required functionality as a whole, regardless of deployment architecture.

We define these components as follows:

Issuer Coordinator • Verifier Coordinator • Holder Coordinator

Coordinators execute 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 VC ecosystem.

Coordinators may or may not provide a visual user interface, depending on the implementation. Pure command-line or continuously running services may 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.

The 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 App and back-end services are out of scope for the VC-API. The Issuer Coordinator drives the Issuer service.

The Verifier Coordinator communicates with a Verifier service to first check authenticity and timeliness of a given VC or VP, then Applies the Verifier's business rules before ultimately accepting or rejecting that VC or VP. Such business rules may include evaluating the Issuer of a particular claim or simply checking a configured allow-list. The Verifier App exposes an API for submitting VCs to the Verifier per the Verifier's policies. For example, the Verifier Coordinator may only accept VCs from current users of the Verifier's other services. These rules typically require bespoke integration with the Verifier's existing back-end.

The Holder Coordinator executes the business rules for Approving the flow of credentials under the control of the Holder, from Issuers to Verifiers. In several deployments this means exposing a user interface that gives individual Holders a visual way to authorize or Approve VC storage or transfer. Some functionality of the Holder Coordinator is commonly referred to as a wallet. In the VC API, the Holder Coordinator initiates all flows. They request VCs from Issuers. They decide if, and when, to share those VCs with Verifiers. Within the VC API, there is no way for either the Issuer or the Verifier to initiate a VC transfer. 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 VCs, even if only at the step of authorizing the transfer. However, many VCs are about organizations, not individuals. How individuals using Holder Coordinators related to organizations, and in particular, how organizational credentials are securely shared with, and presented by, (legal) agents of those organizations is not yet specified as in scope for the VC API.

Issuer Service • Verifier Service • Holder Service

Services provide generic VC API functionality, driven by its associated App. Designed to enable infrastructure providers to offer VC capability through Software-as-a-Service. All services expose network endpoints to their authorized Coordinators, which are themselves operating on behalf of the associated role. Although deployed services MAY provide their own HTML interfaces, such interfaces are out of scope for the VC API. Only the network endpoints of services are defined herein.

The Issuer Service takes requests to issue VCs from authorized Issuer Coordinators and returns well-formed, signed Verifiable Credentials. This service MUST have access to private keys (or key services which utilize private keys) in order to create the proofs for those VCs. The API between the Issuer service and its associated key service is believed to be out of scope for the VC API, but may be addressed by WebKMS or similar specifications.

The 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 VC; leaving the Verifier Coordinator to finish Applying any business rules needed.

The Holder service takes requests to create Verifiable Presentations from an optional set of VCs and returns well-formed, signed Verifiable Presentations containing those VCs. These VPs are used with Issuers to demonstrate control over DIDs prior to issuance and with Verifiers to present specific VCs.

The Status Service provides a privacy-preserving means for 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 external well known specifications, such as the [VC-BITSTRING-STATUS-LIST].

Storage Service (Issuer) •Storage Service (Verifier) • Storage Service (Holder)

Each actor in the system is expected to store their own verifiable credentials, as needed. Several known implementations use secure data storage such as encrypted data vaults for storing the Holder's VCs and use cryptographic authorizations to grant access to those VCs to Verifier Coordinators, as directed by the Holder. In-browser retrieval of such stored credentials can enable web-based Verifier Coordinators 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 the VC 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.

The 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 authorized access to those exchanges to any party.

Issuer Admin • Holder Admin • Verifier Admin

The Admin component 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 may use JSON files to drive a semi-automated Issuer. Others might expose HTML pages. We expect different Coordinators and Services to compete on the power, ease, and flexibility of their administration and therefore, as of this writing, we anticipate Admin functionality to be out of scope for the VC API. However, we actually believe that to the extent we can standardize configuration setting across implementations, the more substitutable each component.

Based on this architectural thinking, we may want to frame the VC API as a roadmap of related specifications, integrated in an extensible way for maximum substitutability. Several technologies, such as EDVs and WebKMSs would likely benefit from the crypto suite Approach taken for VC proofs. Defining a generic mechanism that can be realized by any functionally conformant technology enables flexibility while laying the groundwork with current existing functionality. In this way, we may be able to acknowledge that elements like Key Services, Storage, and Status are necessary parts of the VC API while deferring the definition of how those elements work to specification already in development as well as those yet to be written.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A conforming VC API client is ...

A conforming VC API server is ...

This section is non-normative.

The following terms are used to describe concepts in this specification.

claim: An assertion made about a subject.
credential: A set of one or more claims made by an issuer. The claims in a credential can be about different subjects.
Our definition of credential differs from, NIST's definitions of credential.
data minimization: The act of limiting the amount of shared data strictly to the minimum necessary to successfully accomplish a task or goal.
decentralized identifier: A portable URL-based identifier, also known as a DID, associated with an entity. These identifiers are most often used in a verifiable credential and are associated with subjects such that a verifiable credential itself can be easily ported from one credential repository to another without the need to reissue the credential. An example of a DID is did:example:123456abcdef.
decentralized identifier document: Also referred to as a DID document, this is a document that is accessible using a verifiable data registry and contains information related to a specific decentralized identifier, such as the associated credential repository and public key information.
default graph: The graph containing all claims that are not explicitly part of a named graph.
derived predicate: A verifiable, boolean assertion about the value of another attribute in a verifiable credential. These are useful in zero-knowledge-proof-style verifiable presentations because they can limit information disclosure. For example, if a verifiable credential contains an attribute for expressing a specific height in centimeters, a derived predicate might reference the height attribute in the verifiable credential demonstrating that the issuer attests to a height value meeting the minimum height requirement, without actually disclosing the specific height value. For example, the subject is taller than 150 centimeters.
digital signature: A mathematical scheme for demonstrating the authenticity of a digital message.
entity: Anything that can be referenced in statements as an abstract or concrete noun. Entities include but are not limited to people, organizations, physical things, documents, abstract concepts, fictional characters, and arbitrary text. Any entity might perform roles in the ecosystem, if it is capable of doing so. Note that some entities fundamentally cannot take actions, e.g., the string "abc" cannot issue credentials.
graph: A set of claims, forming a network of information composed of subjects and their relationship to other subjects or data. Each claim is part of a graph; this is either explicit in the case of named graphs, or implicit for the default graph.
holder: A role an entity might perform by possessing one or more verifiable credentials and generating verifiable presentations from them. A holder is often, but not always, a subject of the verifiable credentials they are holding. Holders store their credentials in credential repositories.
identity: The means for keeping track of entities across contexts. Digital identities enable tracking and customization of entity interactions across digital contexts, typically using identifiers and attributes. Unintended distribution or use of identity information can compromise privacy. Collection and use of such information should follow the principle of data minimization.
identity provider: An identity provider, sometimes abbreviated as IdP, is a system for creating, maintaining, and managing identity information for holders, while providing authentication services to relying party applications within a federation or distributed network. In this case the holder is always the subject. Even if the verifiable credentials are bearer credentials, it is assumed the verifiable credentials remain with the subject, and if they are not, they were stolen by an attacker. This specification does not use this term unless comparing or mapping the concepts in this document to other specifications. This specification decouples the identity provider concept into two distinct concepts: the issuer and the holder.
issuer: A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder.
named graph: A graph associated with specific properties, such as verifiableCredential. These properties result in separate graphs that contain all claims defined in the corresponding JSON objects.
presentation: Data derived from one or more verifiable credentials, issued by one or more issuers, that is shared with a specific verifier.
credential repository: A program, such as a storage vault or personal verifiable credential wallet, that stores and protects access to holders' verifiable credentials.
selective disclosure: The ability of a holder to make fine-grained decisions about what information to share.
subject: A thing about which claims are made.
user agent: A program, such as a browser or other Web client, that mediates the communication between holders, issuers, and verifiers.
validation: The assurance that a claim from a specific issuer satisfies the business requirements of a verifier for a particular use. This specification defines how verifiers verify verifiable credentials and verifiable presentations.
It also specifies that verifiers validate claims in verifiable credentials before relying on them. However, the means for such validation vary widely and are outside the scope of this specification. It is expected that verifiers will trust certain issuers for certain claims and apply their own rules to determine which claims in which credentials are suitable for use by their systems.
verifiable credential: A verifiable credential is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to build verifiable presentations, which can also be cryptographically verified.
verifiable data registry: A role a system might perform by mediating the creation and verification of identifiers, keys, and other relevant data, such as verifiable credential schemas, revocation registries, issuer public keys, and so on, which might be required to use verifiable credentials. Some configurations might require correlatable identifiers for subjects. Some registries, such as ones for UUIDs and public keys, might just act as namespaces for identifiers.
verifiable presentation: A verifiable presentation is a tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations might contain data that is synthesized from, but do not contain, the original verifiable credentials (for example, zero-knowledge proofs).
verification: The evaluation of whether a verifiable credential or verifiable presentation is an authentic and current statement of the issuer or presenter, respectively. This includes checking that: the credential (or presentation) conforms to the specification; the proof method is satisfied; and, if present, the status check succeeds. Verification of a credential does not imply evaluation of the truth of claims encoded in the credential.
verifier: A role an entity performs by receiving one or more verifiable credentials, optionally inside a verifiable presentation for processing. Other specifications might refer to this concept as a relying party.
verification material: Information that could be a cryptographic public key or any other data used to verify a proof.
URL: A Uniform Resource Locator, as defined by [URL]. URLs can be dereferenced such that they result in a resource, such as a document. The rules for dereferencing, or fetching, a URL are defined by the URL scheme. This specification does not use the term URI or IRI because those terms have been deemed to be confusing to Web developers.

There are no restrictions put on the base URL location of the implementation. 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., example.com), a subdomain (e.g., api.example.com), or a path within that host (e.g., example.com/api).

The VC API can be deployed in a variety of networking environments which might contain hostile actors. As a result, conforming VC API servers require conforming VC API clients 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, the VC API is agnostic regarding authorization mechanism.

The VC 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 a VC 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 the VC 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:

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.

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 supported by the VC API as services are expected to be known by the coordinator at the time of coordinator deployment.

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.

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.

Many of the endpoints defined in the following sections receive data and options in request bodies.

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

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 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 Status Service, along with the component that is expected to call the endpoint

Below are all endpoints expected to be exposed by the Verification Service, 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 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 issuer instance configuration. 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, 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 issuer instance configuration and the intended use case for the verifiable credential.

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.

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.

The following APIs are defined for presenting a Verifiable Credential:

The URL path values exchange-id and transaction-id are meaningful to the server but are 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 VC API 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. Examples of VC API workflows include, but are not limited to:

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 VC API issuer and/or verification services.

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

A VC API exchange represents a particular interaction based on a given VC API 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. While there is no technical limitation on the number of steps in a workflow, implementers might want to use 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 VC 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.

VC API exchanges are designed to be executable using other protocols in addition to the VC API exchange protocol; for example, an exchange could potentially be executable with any of the OID4VCI, OID4VP, DIDComm, and VC API 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 the VC 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 VC API to interact with the exchange; see Appendix TBD to see how to combine VC API exchanges with other protocols such as OID4VCI, OID4VP, and DIDComm.

Exchanges that are executed using the VC 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 the VC 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 VC API 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 a VC API 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 the VC 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, VC API components (such as an issuer coordinator) make use of mechanisms outside the VC 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.

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.

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 3 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 the VC 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 4 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 5 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 website protocol:

Figure 6 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 the VC API. The interaction URL SHOULD be an HTTPS URL that contains a transaction-specific interaction 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 1: An interaction URL

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

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 7 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 the following response:

Example 2: A list of protocols supported for a given interaction

{
  "protocols": {
    "website": "https://app.example/redirects/z8j3kfk2lQ",
    "vcapi": "https://app.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'"
  }
}

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 website interaction protocol is used by a local system to signal to the remote system that it would like to redirect the remote system to a specific URL, such as a website where an individual can engage in a use-case specific interaction. If the website interaction protocol is selected, the local system sends data using an HTTP POST to instruct the remote system where to send the individual. An example of the POST data is shown below:

Example 3: A website interaction protocol redirect request

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

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

Example 4: 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/vc-api#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 5: 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 1

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

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

Verifiable Credentials API v0.7

An HTTP API for Verifiable Credentials lifecycle management

Abstract

Status of This Document

1. Introduction

1.1 Design Goals and Rationale

1.1.1 Design Guidelines

1.2 Architecture Overview

1.2.1 Coordinators

1.2.2 Services

1.2.3 Status Service

1.2.4 Storage Services

1.2.5 Workflow Service

1.2.6 Admin

1.2.7 Summary

1.3 Conformance

2. Terminology

3. The VC API

3.1 Base URL

3.2 Authorization

3.2.1 Forbidden Authorization

3.2.2 OAuth 2.0

3.3 Service Instances

3.4 Options

3.4.1 Options Extensibility

3.5 Content Serialization

3.6 Handling Unknown Options and Data

3.6.1 Payload Sizes

3.7 API Component Overview

3.7.1 Issuer Coordinator

3.7.2 Issuer Service

3.7.3 Status Service

3.7.4 Verification Service

3.7.5 Holder Service

3.7.6 Workflow Service

3.8 Issuing

3.8.1 Issue Credential

3.8.2 Get a Specific Credential

3.8.3 Update Status

3.9 Verifying

3.9.1 Verify Credential

3.9.2 Verify Presentation

3.9.3 Create Challenge

3.10 Presenting

3.10.1 Derive Credential

3.10.2 Create Presentation

3.10.3 Exchange Discovery

3.10.4 Get Presentations

3.10.5 Get a Specific Presentation

3.11 Workflows and Exchanges

3.11.1 Create Workflow

3.11.2 Get Workflow Configuration

3.11.3 Create Exchange

3.11.4 Participate in an Exchange

3.11.5 Get Exchange State

3.11.6 Exchange Examples

3.12 Initiating Interactions

3.12.1 Interaction URL Format

3.12.2 Interaction QR Code Format

3.12.3 Interaction Protocols Response

3.12.4 website Interaction Protocol

3.12.5 vcapi Interaction Protocol

3.13 Error Handling

3.13.1 Verification Errors vs. Warnings

A. Privacy Considerations

A.1 Delegation

A.2 "Phoning Home" Considered Harmful

B. Security Considerations

B.1 Use of HTTPS for Interaction URLs

B.2 Deletion

B.3 Payload Sizes

B.4 Additional Validation

C. Acknowledgements

D. References

D.1 Normative references

D.2 Informative references

3.12.4 `website` Interaction Protocol

3.12.5 `vcapi` Interaction Protocol