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

Design Goals

Goal Description
TBD TBD

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 App, 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 Apps, 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 App 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:

Apps

Issuer App • Verifier App • Holder App

Apps execute the business rules and policies set by the associated role. Often this is a custom or proprietary App developed specifically for a single party acting in that role, it is the integration glue that connects the controlling party to the VC ecosystem.

Apps 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 Apps acting on behalf of its particular actor to fulfill its role.

The Issuer App executes the rules about who gets what credentials, including how the parties creating or receiving those credentials are authenticated and authorized. Typically the Issuer App 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 App drives the Issuer service.

The Verifier App 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 App 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 App 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 App is commonly referred to as a wallet. In the VC API, the Holder App 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 of the Verifier to initiate a VC transfer. In many scenarios, the Holder App 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 Apps 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 Apps, 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 Apps 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 App 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)

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 Apps, as directed by the Holder. In-browser retrieval of such stored credentials can enable web-based Verifier Apps 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 Apps, 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 Apps 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

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 verifyig 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 App to ensure the Holder App can support the exchange protocol requirements before calling the endpoint. Apps 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 App and responded to by any App that implements exchanges. The flows consist of the following steps:

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

The Holder App MAY call the App's exchange discovery endpoint to determine if the Holder App supports the App'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 App (Wallet)
    participant I as Issuer/Verifier App
    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": "DIDAuth"
      }, {
        "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

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

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

Security Considerations

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.