Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
TODO: write a real abstract
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document represents a concise but limited collection of use cases readers should review alongside the VC API Specification.
Comments regarding this document are welcome. Please file directly on GitHub, or send them to public-vc-comments@w3.org (subscribe, archives).
This document was published by the VC API Working Group as a Working Group Note.
GitHub Issues are preferred for discussion of this specification.
Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2019 W3C Process Document.
For Verifiable Credentials to be realized as a usable data format there needs to exist a neutral, standard-governed way for Issuers, Holders and Verifiers of these credentials to transport them between said entities. TODO: Finish introduction
TODO: fill in
Lana is an IT administrator for the United States Citizenship and Immigration Services (USCIS) Digital Permanent Resident Card (PRC) program. She configures the USCIS website to issue digital Permanent Resident Cards by utilizing industry standard issuer software and setting up the appropriate HTTP API Authorizations between systems. Legal Permanent Residents, upon receiving their physical card in the mail, are given the USCIS website URL, a login account, and PIN code that they may use to manage their account and pick up their digital Permanent Resident Card. When Louis, a Legal Permanent Resident, requests a digital Permanent Resident Card via the USCIS website, he authenticates using his login account and once authenticated, provides a DID associated with his client-side digital wallet against which the website will issue VCs. The USCIS website then connects to the digital card issuing server, which builds the Verifiable Credential Permanent Resident Card using Louis' account data, and then utilizes industry standard HTTP APIs to issue the Permanent Resident Card as a Verifiable Credential. Louis can then use his Digital Permanent Resident Card in online scenarios when he needs to prove his resident status, such as when applying for a job.
Requirements:
Contributed by: Digital Bazaar
Mermaid
Riley has onboarded into the TruAge digital age verification system, which has provided her with a set of Verifiable Credentials that she stores in her digital wallet. A subset of the Verifiable Credentials that she has received are digitally signed single-use age tokens that only assert that she is above the age of 21 and are marked as "used" by the TruAge system when they are submitted as a part of an age-restricted goods purchase, such as buying a bottle of wine. Eventually, Riley runs out of single use age tokens in her digital wallet. The digital wallet keeps track of which tokens have been used and once all tokens have been consumed, contacts a refresh service endpoint listed in one of the TruAge credentials that provides new over-age tokens. The digital wallet requests a new set of tokens by hitting the HTTP API of this VC-refresh service listed in the “refreshService” array and POSTing the original Verifiable Credential containing the refresh service description. The HTTP API ensures that it has received a valid credential and reissues a set of new digitally signed single-use age tokens in the response.
Requirements:
Mermaid
Contributed by: Digital Bazaar
Description: Ignio, a logistics manager for "Kirk Company", would like to submit all necessary paperwork to send his company's products across international boundaries. These products are considered hazardous chemicals and thus are regulated, requiring extra paperwork to be filed before transportation is approved across boundaries. Some hazardous material shipments are different resulting in different required paperwork, and Ignio wants to automate as much of the process as possible with Shippers, their 3rd Party Logistics company (3PL). There are a set of verifiable credentials that Ignio is willing to share with Customs as well as the transportation company.
When Kirk starts a shipping workflow, his company's systems initiate the workflow by contacting a known location on the Shipper's Website. A presentation exchange occurs to first DIDAuth the company and send generic mandatory information for any shipment; if and only if the information provided requires additional information‒in this case a hazmat certification‒a second exchange is initiated to request this outstanding/required hazmat info. Once this is received, Shippers can send back a Bill of Lading in VC form. The two (or more) credential exchanges are composable and idempotent, ending in a valid BoL if successful.
Requirements:
Mermaid
Contributed by: Digital Bazaar
Tod is using digital credentials to apply for a service/qualify for a job/gain access to a programme. Some of his credentials are available today, some will need to be provided when they are ready (for example, a criminal background check can take 24-48 hrs to process). He would like these credentials to be presented to the Verifier (service provider) when ready, without having to constantly return to the Verifier (service provider) and deliver them "by hand". He should be able to have them released from his Holder directly as they become available.
Requirements:
Mermaid
Contributed by:SecureKey Technologies Inc.
A student, Shabazz, wants to publish their MBLEx test results from an education test provider, Massage Therapy Test Corp. Massage Therapy Test Corp proxies their authority to sign to a service provider, SSI Ventures. SSI Ventures issues Shabazz a VC when he logs into his Massage Therapy Test Corp account and enables his browser-based SSI Wallet, Billfold. The signed VC is then stored in Shabazz’ Billfold™ Wallet to be presented elsewhere.
In a separate session, Shabazz logs into a web portal of a State Massage Therapy licensure system to apply for his Massage Therapy license. The licensure specialist at the State checks the issuer using a State accreditation system, then checks the signature on the test results VC and ingests the credential’s payload. The licensure specialist then finalizes their workflow and issues Shabazz a Massage Therapy license.
Requirements:
Mermaid
sequenceDiagram
autonumber
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):massagetherapytestcorp.com
Shabazz's Billfold
(Holder App - includes browser)->>Massage Therapy Test Corp Webpage
(Issuer App):messagetherapytestcorp.com/index.html
Massage Therapy Test Corp Webpage
(Issuer App)->>Shabazz's Billfold
(Holder App - includes browser):index.html
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):display webpage
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):Authenticate
Shabazz's Billfold
(Holder App - includes browser)->>Massage Therapy Test Corp Webpage
(Issuer App):messagetherapytestcorp.com/authenticate
Massage Therapy Test Corp Webpage
(Issuer App)->>Shabazz's Billfold
(Holder App - includes browser):authentication challenge
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):challenge
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):authentication information
Shabazz's Billfold
(Holder App - includes browser)->>Massage Therapy Test Corp Webpage
(Issuer App):messagetherapytestcorp.com/authenticate?"info"
Massage Therapy Test Corp Webpage
(Issuer App)->>Massage Therapy Test Corp Webpage
(Issuer App):process authentication information
Massage Therapy Test Corp Webpage
(Issuer App)->>Shabazz's Billfold
(Holder App - includes browser):authentication success
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):authentication success
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):get Message Therapy Credential
Shabazz's Billfold
(Holder App - includes browser)->>Massage Therapy Test Corp Webpage
(Issuer App):messagetherapytestcorp.com/getTherapyCredential
Massage Therapy Test Corp Webpage
(Issuer App)->>Shabazz's Billfold
(Holder App - includes browser):DID Auth Challenge
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):Display wallet selector
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):Selected Wallet
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):Display profile selector
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):Selected Profile
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz's Wallet
(Holder Service):Request DID Auth Challenge Responsew
Shabazz's Wallet
(Holder Service)->>Shabazz's Wallet
(Holder Service):generate DID Auth response
Shabazz's Wallet
(Holder Service)->>Shabazz's Billfold
(Holder App - includes browser):DID Auth response
Shabazz's Billfold
(Holder App - includes browser)->>Massage Therapy Test Corp Webpage
(Issuer App):messagetherapytestcorp.com/getTherapyCredential/didAuth?"DIDAuthResponse"
Massage Therapy Test Corp Webpage
(Issuer App)->>Massage Therapy Test Corp Webpage
(Issuer App):Process response
Massage Therapy Test Corp Webpage
(Issuer App)->>SSI Venture
(Issuer Service):ssiventures.com/messagetestcorp/credentials/issue?"VPfromDIDAuth"
SSI Venture
(Issuer Service)->>Massage Therapy Test Corp Webpage
(Issuer App):messagetherapytestcorp.com/credentials/issued?"issuedCredentailsWrappedByIssuerApp"
Massage Therapy Test Corp Webpage
(Issuer App)->>Shabazz's Billfold
(Holder App - includes browser):HolderApp/newCredential?"issuedCredentialUnwrappedByIssuerApp"
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz's Wallet
(Holder Service):store credential
Shabazz's Wallet
(Holder Service)->>Shabazz's Billfold
(Holder App - includes browser):success
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):Credential successfully stored in wallet
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):Go to Floyd's Message Therapy Webpage
Shabazz's Billfold
(Holder App - includes browser)->>floydsmassagetheray.com
(Verifier App):floydsmessagetherapy.com/index.html
floydsmassagetheray.com
(Verifier App)->>Shabazz's Billfold
(Holder App - includes browser):index.html
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):display page
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):Submit employment application
Shabazz's Billfold
(Holder App - includes browser)->>floydsmassagetheray.com
(Verifier App):floydsmessagetherapy.com/employmentApp
floydsmassagetheray.com
(Verifier App)->>Shabazz's Billfold
(Holder App - includes browser):Domain&Challenge
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):Display wallet selector
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):wallet selection
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):Display profile selector
Shabazz
(Holder)->>Shabazz's Billfold
(Holder App - includes browser):Selected Profile
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz's Wallet
(Holder Service):Domain&Challenge
Shabazz's Wallet
(Holder Service)->>Shabazz's Wallet
(Holder Service):generate VP
Shabazz's Wallet
(Holder Service)->>Shabazz's Billfold
(Holder App - includes browser):Challenge response VP
Shabazz's Billfold
(Holder App - includes browser)->>floydsmassagetheray.com
(Verifier App):floydsmessagetherapy.com/empoymentApp/challengeResponse?"VP"
floydsmassagetheray.com
(Verifier App)->>floydsmassagetheray.com
(Verifier App):Process response
floydsmassagetheray.com
(Verifier App)->>Shabazz's Billfold
(Holder App - includes browser):request application with State License VC
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz's Wallet
(Holder Service):Request VP
Shabazz's Wallet
(Holder Service)->>Shabazz's Wallet
(Holder Service):Generate VP
Shabazz's Wallet
(Holder Service)->>Shabazz's Billfold
(Holder App - includes browser):VP w/Application and State License
Shabazz's Billfold
(Holder App - includes browser)->>floydsmassagetheray.com
(Verifier App):floydsmessagetherapy.com/presenatations/submit?"Application wtih State License VP"
floydsmassagetheray.com
(Verifier App)->>State Verifier (Verifier Service):stateverifier.com/credentials/verify?"StateLicenseVC"
State Verifier (Verifier Service)->>floydsmassagetheray.com
(Verifier App):Verification Result
floydsmassagetheray.com
(Verifier App)->>floydsmassagetheray.com
(Verifier App):process application
floydsmassagetheray.com
(Verifier App)->>Shabazz's Billfold
(Holder App - includes browser):Application submitted
Shabazz's Billfold
(Holder App - includes browser)->>Shabazz
(Holder):Application submitted
Contributed by:RANDA Solutions
In order to export steel products to the global market, Steel Mills Global must prove the quality of their products. For this, they rely on Inspectors & Co, an internationally recognized steel testing company. Upon inspection, Inspectors & Co issues a Mill Test Report VC to Steel Mills Global.
Steel, Inc. imports and distributes steel products domestically. Negotiating a shipment Steel Mills Global presents the MTR as proof of product quality. Steel Inc. verifies the MTR VP and accepts the shipment.
Steel, Inc. initiates the importing procedures, starting out self-issuing an Import Declaration Form VC. The MTR and IDF are jointly presented to the Customs authority which verifies the VP. Upon verification the customs release is granted for goods import.
Note: These VC types are taken from the Traceability Vocabulary, a W3C-CCG work item for supply chain use-cases.
Requirements:
Mermaid
sequenceDiagram
autonumber
Holder - Steel Mills Global (SMG)->>Holder App - SMG Enterprise API:getMillTestReportVC
Holder App - SMG Enterprise API->>Issuer App - Inspectors & Co Enterprise Software:inspectorandco.com/credentials/issue
Issuer App - Inspectors & Co Enterprise Software->>Lacy - Inspectors & Co Inspector:New inspection requested
Lacy - Inspectors & Co Inspector->>Lacy - Inspectors & Co Inspector:Completes SMG Inspection
Lacy - Inspectors & Co Inspector->>Issuer App - Inspectors & Co Enterprise Software:Issue Mill Test Report to SMG
Issuer App - Inspectors & Co Enterprise Software->>Issuer Service - Inspectors & Co Issuer:IandCoIssuer.com/credentials/issue
Issuer Service - Inspectors & Co Issuer->>Issuer Service - Inspectors & Co Issuer:Process request
Issuer Service - Inspectors & Co Issuer->>Issuer App - Inspectors & Co Enterprise Software:Issued Credentials
Issuer App - Inspectors & Co Enterprise Software->>Holder App - SMG Enterprise API:smgApi.com/credentials/recieve?\"MillTestReportVP\"
Holder App - SMG Enterprise API->>Holder App - SMG Enterprise API:Process returned VP
Holder App - SMG Enterprise API->>Holder Service - SMG Wallet:smgWallet.com/credentials/store?\"MTRVP\"
Holder Service - SMG Wallet->>Holder Storage - SMG EDV/KMS:smgEdv.com/credentials/store?\"MTRVP\"
Holder Storage - SMG EDV/KMS->>Holder Storage - SMG EDV/KMS:Store credentials
Holder Storage - SMG EDV/KMS->>Holder Service - SMG Wallet:Storage success and access info
Holder Service - SMG Wallet->>Holder App - SMG Enterprise API:Storage acknowledged
Holder App - SMG Enterprise API->>Holder - Steel Mills Global (SMG):Mill Test Report recieved
Steel, Inc->>Holder - Steel Mills Global (SMG):Purchase Inquiry
Holder - Steel Mills Global (SMG)->>Holder - Steel Mills Global (SMG):Process Inquiry
Holder - Steel Mills Global (SMG)->>Steel, Inc:Agree to sell
Steel, Inc->>Holder - Steel Mills Global (SMG):Request Mill Test Report
Holder - Steel Mills Global (SMG)->>Holder App - SMG Enterprise API:sendMillTestReportVC
Holder App - SMG Enterprise API->>Verifier App - Steel, Inc. Business API:steelincapi.com/presentations/available
Verifier App - Steel, Inc. Business API->>Holder App - SMG Enterprise API:Domain&Challenge
Holder App - SMG Enterprise API->>Holder Service - SMG Wallet:smgWallet.com/presentations/issue?\"Domain&Challenge\"
Holder Service - SMG Wallet->>Holder Service - SMG Wallet:Generate VP containing the MTR
Holder Service - SMG Wallet->>Holder Storage - SMG EDV/KMS:smgEdv.com/credentials/sign?\"GeneratedVP\"
Holder Storage - SMG EDV/KMS->>Holder Storage - SMG EDV/KMS:Sign VP
Holder Storage - SMG EDV/KMS->>Holder Service - SMG Wallet:SignedVP
Holder Service - SMG Wallet->>Holder App - SMG Enterprise API:SignedVP
Holder App - SMG Enterprise API->>Verifier App - Steel, Inc. Business API:steelincapi.com/presentations/submissions?\"SignedVP\"
Verifier App - Steel, Inc. Business API->>Verifier App - Steel, Inc. Business API:Check business rules
Verifier App - Steel, Inc. Business API->>Verifier Service - Steel Industry Verifier:steelindustryverifier.com/presentations/verify
Verifier Service - Steel Industry Verifier->>Verifier Service - Steel Industry Verifier:Check proofs
Verifier Service - Steel Industry Verifier->>Issuer Service - Inspectors & Co Issuer:IandCoIssuer.com/credentials/revocationList?\"MTRVC\"
Issuer Service - Inspectors & Co Issuer->>Issuer Service - Inspectors & Co Issuer:Check revocation list
Issuer Service - Inspectors & Co Issuer->>Verifier Service - Steel Industry Verifier:revocationStatus=notRevoked
Verifier Service - Steel Industry Verifier->>Verifier App - Steel, Inc. Business API:steelincapi.com/presentations/verified?\"MTRVC\"
Verifier App - Steel, Inc. Business API->>Verifier App - Steel, Inc. Business API:Check business rules
Verifier App - Steel, Inc. Business API->>Verifier App - Steel, Inc. Business API:Record verification result
Verifier App - Steel, Inc. Business API->>Steel, Inc:New Verification Result Notification
Verifier App - Steel, Inc. Business API->>Holder App - SMG Enterprise API:steelincapi.com/presentations/verified?\"SignedVP\"
Holder App - SMG Enterprise API->>Holder - Steel Mills Global (SMG):Mill Test Report Verified
Contributed by:Transmute Industries
Cannot GET /uploads/6QPst4/terms.html
This section is non-normative.
The editors are thankful to the contributions from the VC API Working Group