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 specification is highly experimental and changing rapidly. Implementation in non-experimental systems is discouraged unless you are participating in the weekly meetings that coordinate activity around this specification.

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-credentials@w3.org ( subscribe, archives).

Introduction

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:

Design Goals and Rationale

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.

Architecture Overview

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

Coordinators

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.

Services

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.

Status Service

The Status Service provides a privacy-preserving means for publishing and checking the status of any Verifiable Credentials issued by the Issuer. Verifier services use the Issuer's status endpoint (as specified in each revocable verifiable credential) to check the timeliness of a given VC as part of verification.

Storage Services

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

Workflow Service

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.

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.

Admin

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.

Summary

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.

A conforming VC API client is ...

A conforming VC API server is ...

Terminology

The VC API

Base URL

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

Authorization

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.

This section details 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.

Forbidden Authorization

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

OAuth 2.0

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.

Issuing

The following APIs are defined for issuing a Verifiable Credential:

Issue Credential

Get Credentials

Get a Specific Credential

Update Status

Verifying

The following APIs are defined for verifying a Verifiable Credential:

Verify Credential

Verify Presentation

Presenting

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.

Derive Credential

Prove Presentation

Exchange Discovery

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.

Get Presentations

Get a Specific Presentation

Initiate Exchange

Continue Exchange

Exchange Examples

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:

  1. The Holder Coordinator contacts the receiving Coordinator to request the initiation of a particular exchange.
  2. 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.
  3. The Holder Coordinator responds to the receiving Coordinator with a Verifiable Presentation containing information that will satisfy the presentation request.
  4. 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:

sequenceDiagram
    participant H as Holder
    participant W as Holder Coordinator (Wallet)
    participant I as Issuer/Verifier Coordinator
    autonumber
    Note right of H: Start exchange
    W->>I: Initiate
    Note right of W: POST /exchanges/123 - HTTP request to start exchange (e.g., send credentials, get credentials)
    I->>W: Verifiable Presentation Request (VPR)
    Note left of I: VPR includes method of interaction, for purposes of exchange
    W->>I: Verifiable Presentation (VP)
    Note right of W: POST /exchanges/123/session-abc - sent via interaction mechanism to meet requirements of exchange
    I->>W: Verifiable Presentation
    Note left of I: VP includes result of exchange (e.g., VCs), or VPR with new interaction request, or error description
          
A standard exchange between a Holder and an Issuer/Verifier.

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

The following example demonstrates a fully automated flow for performing a Verifiable Credential refresh that follows the generic flow mentioned above:

POST /exchanges/refresh-degree HTTP/1.1
Host: example.edu
Content-Type: application/json
Accept: application/json, */*
Accept-Encoding: gzip, deflate
        
HTTP/1.1 201 Created
Date: Fri, 14 Jun 2022 18:37:12 GMT
Connection: keep-alive

{
  "verifiablePresentationRequest": {
    "query": [{
        "type": "DIDAuthentication"
      }, {
        "type": "QueryByExample",
        "credentialQuery": {
          "reason": "We need to see your existing University Degree credential.",
          "example": {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "type": "UniversityDegreeCredential"
          }
        }
      }],
      "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
      "domain": "example.edu",
      "interact": {
        "service": [{
          "type": "UnmediatedPresentationService2021",
          "serviceEndpoint": "https://example.edu/exchanges/refresh-degree/0bc42ece-89f7-11ec-9af0-136dfa9e4dbb"
        }]
      }
    }
  }
}
        

Readers are urged to pay particular attention to the `interact` service description that provides a mechanism to switch between automated flows and ones requiring mediation by a person.

While the example above utilizes a Verifiable Presentation Request, other types of equivalent presentation request formats, such as WACI/PeX, can be utilized (simultaneously or alternatively) based on the presentation request formats that are supported by the Issuer. Automated requests can be signalled by setting the service `type` to `UnmediatedPresentationService2021`, while manual requests can be signalled by setting the service `type` to `MediatedPresentationService2021`.

POST /exchanges/refresh-degree/0bc42ece-89f7-11ec-9af0-136dfa9e4dbb HTTP/1.1
Host: example.edu
Content-Type: application/json
Accept: application/json, */*
Accept-Encoding: gzip, deflate

{
  "verifiablePresentation": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "type": ["VerifiablePresentation"],
    "holder": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "verifiableCredential": [{
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1",
        "https://w3id.org/security/suites/ed25519-2020/v1"
      ],
      "id": "http://example.edu/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": "https://example.edu/issuers/14",
      "issuanceDate": "2010-01-01T19:23:24Z",
      "expirationDate": "2022-01-01T19:23:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      },
      "refreshService": {
        "type": "AutoRefresh2021",
        "url": "https://example.edu/exchanges/refresh-degree",
        "validAfter": "2021-09-01T19:23:24Z"
      },
      "proof": {
        "type": "Ed25519Signature2020",
        "created": "2021-12-05T17:59:45Z",
        "verificationMethod": "https://example.edu/issuers/14#key-1",
        "proofPurpose": "assertionMethod",
        "proofValue": "z2aArNcQKX9aqYK7GRZmV7c9xfGuwB5YAXhkYY9DTvLdTCQEsXaNpz1G
                       ZL9XDXdFQGT27WB68e2Y3wo9k75rka8oo"
      }
    }],
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2022-06-15T16:37:12Z",
      "verificationMethod": "did:example:76e12ec712ebc6f1c221ebfeb1f#key-1",
      "proofPurpose": "authentication",
      "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
      "domain": "example.edu",
      "proofValue": "z4aU6NSpnCvnjJqzAPw3cqJ1LKoWimEWxKz7StJYzwaZE2a3QAuK8vcq
                     umwr6uabr7RshvjH1yTv1fTuhPUii1fN"
    }
  }
}
        
HTTP/1.1 200 OK
Date: Fri, 14 Jun 2022 18:37:12 GMT
Connection: keep-alive

{
  "verifiablePresentation": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": ["VerifiablePresentation"],
    "verifiableCredential": [{
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1",
        "https://w3id.org/security/suites/ed25519-2020/v1"
      ],
      "id": "http://example.edu/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": "https://example.edu/issuers/14",
      "issuanceDate": "2010-01-01T19:23:24Z",
      "expirationDate": "2027-06-14T18:37:12Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      },
      "refreshService": {
        "type": "AutoRefresh2021",
        "url": "https://example.edu/exchanges/refresh-degree",
        "validAfter": "2027-03-14T19:23:24Z",
        "validUntil": "2027-07-14T19:23:24Z"
      },
      "proof": {
        "type": "Ed25519Signature2020",
        "created": "2022-06-14T18:37:12Z",
        "verificationMethod": "https://example.edu/issuers/14#key-1",
        "proofPurpose": "assertionMethod",
        "proofValue": "z2aArNcQKX9aqYK7GRZmV7c9xfGuwB5YAXhkYY9DTvLdTCQEsXaNpz1G
                       ZL9XDXdFQGT27WB68e2Y3wo9k75rka8oo"
      }
    }]
  }
}
        

Privacy Considerations

Delegation

Verifiable credentials [[VC-DATA-MODEL-2.0]] are a standard data model designed to mitigate risks of misuse and fraud. As a data model, verifiable credentials are protocol-neutral and consider at least two types of entities: issuer and subject. When the subject of a verifiable credential is a natural person or linked to a natural person, privacy and human rights can be impacted by the vastly more efficient processing of standardized verifiable credentials as compared to their analog ancestors.

Technology, in the form of standardized APIs and protocols for issuing verifiable credentials, further enhances the efficiency of processing verifiable credentials and adds to the risks of unforeseen privacy and human rights consequences.

Verifiable credentials issuance has a request phase and a delivery phase. The request might be made by the subject or another role, and delivery can be to a client that might or might not be controlled by the subject. Delegation is highly relevant for both phases. The issuer might delegate processing of the request to a separate entity. The subject, for their part, might also delegate the ability to request a verifiable credential to a separate entity. Note that the subject might not always have the capability or ability to perform delegation. Examples include: a new born baby, a pet, and a person with dementia. So the request might be performed by a third party who was not delegated by the subject. The ability to delegate is a third dimension in the enhanced efficiency of processing verifiable credentials and has impact on privacy and human rights.

The architecture described in this specification is designed for market acceptance through a combination of efficiency and respect for privacy and human rights. APIs and protocols for processing verifiable credentials do not favor delegation by the issuer role over delegation by the subject role.

"Phoning Home" Considered Harmful

It is considered a bad privacy practice for a verifier to contact an issuer about a specific verifiable credential. This practice is known as "phoning home" and can result in a mismatch in privacy expectations between holders, issuers, verifiers, and other parties expressed in a verifiable credential. Phoning home enables issuers to correlate unsuspecting parties with the use of certain verifiable credentials which can violate privacy expectations that each entity might have regarding the use of those credentials. For example, what is expected by the holder to be a private interaction between them and the verifier becomes one where the issuer is notified of the interaction.

There are some interactions where contacting the issuer in a privacy-preserving manner upholds the privacy expectations of the holder. For example, contacting the issuer to get revocation status information in a privacy-respecting manner, such as through a status list that provides group privacy can be acceptable as long as the issuer is not able to single out which verifiable credential is being queried based on the retrieval of the status list. For more information on one such mechanism see the [[[VC-BITSTRING-STATUS-LIST]]] specification.

Verifiers are urged to not "phone home" in ways that will create privacy violations. When retrieving content that is linked from a verifiable credential, using mechanisms such as [[[?OHTTP]]] and aggressively caching results can improve the privacy characteristics of the ecosystem.

Security Considerations

Deletion

The APIs provided by this specification enable the deletion of verifiable credentials and verifiable presentations from storage services. The result of these deletions and the side-effects they might cause are out of scope for this specification. However, implementers are advised to understand the various ways deletion can be implemented. There are at least two types of deletion that are contemplated by this specification.

Partial deletion marks a record for deletion but continues to store some or all of the original information. This mode of operation can be useful if there are audit requirements for all credentials and/or presentations over a particular time period, or if recovering an original credential might be a useful feature to provide.

Complete deletion purges all information related to a given verifiable credential or verifiable presentation in a way that is unrecoverable. This mode of operation can be useful when removing information that is outdated and beyond the needs of any audit or when responding to any sort of "right to be forgotten" request.

When deleting a verifiable credential, handling of its status information needs to be considered. Some use cases might call for deletion of a particular verifiable credential to also set the revocation and suspension bits of that verifiable credential, such that any sort of status check for the deleted credential fails and use of the credential is halted.

Given the scenarios above, implementers are advised to allow the system actions that occur after a delete to be configurable, such that system flexibility is sufficient to address any verifiable credential use case.

Acknowledgements

The Working Group thanks the following individuals for their contributions to this specification: The final list of acknowledgements will be compiled at the end of the Candidate Recommendation phase.

Portions of the work on this specification have been funded by the United States Department of Homeland Security's Silicon Valley Innovation Program under contracts 70RSAT20T00000003, 70RSAT20T00000010, 70RSAT20T00000029, 70RSAT20T00000031, 70RSAT20T00000033, and 70RSAT20T00000043. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.

Development of this specification has also been supported by the W3C Credentials Community Group, chaired by Kim Hamilton Duffy, Heather Vescent, and Wayne Chang.