Verifiable Credentials HTTP API v0.3

A HTTP API for Verifiable Credentials lifecycle management

Draft Community Group Report

Latest published version:
https://www.w3.org/TR/vc-http-api/
Latest editor's draft:
https://w3c-ccg.github.io/vc-http-api/
Editor:
TBD
Author:
Participate:
GitHub w3c-ccg/vc-http-api
File an issue
Commit history
Pull requests

Copyright © 2021 the Contributors to the Verifiable Credentials HTTP API v0.3 Specification, published by the Credentials Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

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.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c-ccg.github.io/vc-http-api/ for the Editor's draft.

This specification was published by the Credentials Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

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

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-credentials@w3.org (subscribe, archives).

1. Introduction

This section is non-normative.

1.1 A Simple Example

This section is non-normative.

An example of Verifiable Credential issuance.
Figure 1 A simple example of issuing a Verifiable Credential.

1.2 Design Goals

This section is non-normative.

Goal Description
TBD TBD

1.3 Architecture Overview

This section is non-normative.

This section provides a basic overview of the major components of this specification's architecture.

Diagram showing how credentials flow from issuer to holder and presentations flow from holder to verifier where all three parties can use information from a logical verifiable data registry
Figure 2 The roles and information flows forming the basis for this specification.
Note

The ecosystem overview above is an example ecosystem in which to ground the rest of the concepts in this specification. Other ecosystems exist, such as protected environments or proprietary systems, where verifiable credentials also provide benefit.

Issue 1

TODO: Explain example issuer architecture overview. The blue highlights around some boxes identify APIs defined by this specification.

TODO
Figure 3 A detailed view of an example issuer architecture.
Issue 2

TODO: Explain example holder architecture overview. The blue highlights around some boxes identify APIs defined by this specification.

TODO
Figure 4 A detailed view of an example holder architecture.
Issue 3

TODO: Explain example holder architecture overview. The blue highlights around some boxes identify APIs defined by this specification.

TODO
Figure 5 A detailed view of an example verifier architecture.

1.4 Conformance

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 word SHOULD in this document is 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 ...

2. Terminology

This section is non-normative.

This section defines the terms used in this specification and throughout decentralized identifier infrastructure. A link to these terms is included whenever they appear in this specification.

decentralized identifier (DID)
A globally unique persistent identifier that does not require a centralized registration authority and is often generated and/or registered cryptographically. The generic format of a DID is defined in DID Core: Syntax. Many—but not all—DID methods make use of distributed ledger technology (DLT) or some other form of decentralized network.

3. The VC HTTP API

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

3.1.1 Delegating Authorization

Implementers SHOULD utilize authorization protocols that support authorization delegation in order to minimize authorization credential sharing and maximize an individual's choice in software systems. Examples of these protocols include Authorization Capabilities [ZCAP] and the Grant Negotiation and Authorization Protocol [GNAP].

3.2 Issuing

3.3 Verifying

3.4 Presenting

A. Privacy Considerations

B. Security Considerations

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

D. References

D.1 Normative references

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174

D.2 Informative references

[GNAP]
Grant Negotiation and Authorization Protocol. Justin Richer; Aaron Parecki; Fabien Imbault. IETF. 2021-07-12. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC4122]
A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4122
[VC-DATA-MODEL]
Verifiable Credentials Data Model 1.0. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel. W3C. 2019-11-19. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/
[ZCAP]
Authorization Capabilities 0.x. Chris Webber; Manu Sporny; Mark Miller. W3C CCG. 2021-09-12. Community Draft. URL: https://w3c-ccg.github.io/zcap-ld/