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-api/
Latest editor's draft:
https://w3c-ccg.github.io/vc-api/
Editor:
TBD
Author:

Copyright © 2022 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-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 Design Goals

This section is non-normative.

Goal Description
TBD TBD

1.2 Architecture Overview

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

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

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

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

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

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

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

1.3 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 words MAY, MUST, and MUST 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 ...

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 Forbidden Authorization

Requests to the VC HTTP 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].

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

3.2 Issuing

The following APIs are defined for issuing a Verifiable Credential:

EndpointDescription
POST /credentials/issueIssues a credential and returns it in the response body.
POST /credentials/statusUpdates the status of an issued credential

3.2.1 Issue Credential

POST /credentials/issue - Issues a credential and returns it in the response body.

ResponseDescription
201Credential successfully issued!
400invalid input!
500error!

The /credentials/issue endpoint uses the following schema when receiving a POST:

{
  "credential": {
    "type": "object",
    "description": "A JSON-LD Verifiable Credential without a proof.",
    "properties": {
      "@context": {
        "type": "array",
        "description": "The JSON-LD context of the credential.",
        "items": {
          "type": "string"
        }
      },
      "id": {
        "type": "string",
        "description": "The ID of the credential."
      },
      "type": {
        "type": "array",
        "description": "The JSON-LD type of the credential.",
        "items": {
          "type": "string"
        }
      },
      "issuer": {
        "type": "object",
        "description": "A JSON-LD Verifiable Credential Issuer.",
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            }
          }
        ],
        "example": {
          "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
        }
      },
      "issuanceDate": {
        "type": "string",
        "description": "The issuanceDate"
      },
      "expirationDate": {
        "type": "string",
        "description": "The expirationDate"
      },
      "credentialSubject": {
        "type": "object",
        "description": "The subject"
      }
    },
    "example": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "id": "http://example.gov/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": "did:example:123",
      "issuanceDate": "2020-03-16T22:37:26.544Z",
      "credentialSubject": {
        "id": "did:example:123",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      }
    }
  },
  "options": {
    "type": "object",
    "additionalProperties": false,
    "description": "Options for specifying how the LinkedDataProof is created.",
    "properties": {
      "type": {
        "type": "string",
        "description": "The type of the proof. Default is an appropriate proof type corresponding to the verification method."
      },
      "verificationMethod": {
        "type": "string",
        "description": "The URI of the verificationMethod used for the proof. If omitted, a default verification method will be used."
      },
      "proofPurpose": {
        "type": "string",
        "description": "The purpose of the proof. Default 'assertionMethod'."
      },
      "created": {
        "type": "string",
        "description": "The date and time of the proof (with a maximum accuracy in seconds). Default current system time."
      },
      "challenge": {
        "type": "string",
        "description": "A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2"
      },
      "domain": {
        "type": "string",
        "description": "The intended domain of validity for the proof. For example website.example"
      },
      "credentialStatus": {
        "type": "object",
        "description": "The method of credential status to issue the credential including. If omitted credential status will be included.",
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of credential status to issue the credential with"
          }
        }
      }
    },
    "example": {
      "type": "Ed25519Signature2018",
      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
      "proofPurpose": "assertionMethod",
      "created": "2020-04-02T18:48:36Z",
      "domain": "revocation.example",
      "challenge": "d436f0c8-fbd9-4e48-bbb2-55fc5d0920a8",
      "credentialStatus": {
        "type": "RevocationList2020Status"
      }
    }
  }
}

3.2.2 Update Status

POST /credentials/status - Updates the status of an issued credential

ResponseDescription
200Credential status successfully updated
400Bad Request
404Credential not found
500Internal Server Error

The /credentials/status endpoint uses the following schema when receiving a POST:

{
  "credentialId": {
    "type": "string"
  },
  "credentialStatus": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      }
    }
  }
}

3.3 Verifying

The following APIs are defined for verifyig a Verifiable Credential:

EndpointDescription
POST /credentials/verifyVerifies a verifiableCredential and returns a verificationResult in the response body.
POST /presentations/verifyVerifies a Presentation with or without proofs attached and returns a verificationResult in the response body.

3.3.1 Verify Credential

POST /credentials/verify - Verifies a verifiableCredential and returns a verificationResult in the response body.

ResponseDescription
200Verifiable Credential successfully verified!
400invalid input!
500error!

The /credentials/verify endpoint uses the following schema when receiving a POST:

{
  "verifiableCredential": {
    "type": "object",
    "description": "A JSON-LD Verifiable Credential with a proof.",
    "allOf": [
      {
        "type": "object",
        "description": "A JSON-LD Verifiable Credential without a proof.",
        "properties": {
          "@context": {
            "type": "array",
            "description": "The JSON-LD context of the credential.",
            "items": {
              "type": "string"
            }
          },
          "id": {
            "type": "string",
            "description": "The ID of the credential."
          },
          "type": {
            "type": "array",
            "description": "The JSON-LD type of the credential.",
            "items": {
              "type": "string"
            }
          },
          "issuer": {
            "type": "object",
            "description": "A JSON-LD Verifiable Credential Issuer.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  }
                }
              }
            ],
            "example": {
              "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
            }
          },
          "issuanceDate": {
            "type": "string",
            "description": "The issuanceDate"
          },
          "expirationDate": {
            "type": "string",
            "description": "The expirationDate"
          },
          "credentialSubject": {
            "type": "object",
            "description": "The subject"
          }
        },
        "example": {
          "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://www.w3.org/2018/credentials/examples/v1"
          ],
          "id": "http://example.gov/credentials/3732",
          "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
          ],
          "issuer": "did:example:123",
          "issuanceDate": "2020-03-16T22:37:26.544Z",
          "credentialSubject": {
            "id": "did:example:123",
            "degree": {
              "type": "BachelorDegree",
              "name": "Bachelor of Science and Arts"
            }
          }
        }
      },
      {
        "type": "object",
        "properties": {
          "proof": {
            "type": "object",
            "description": "A JSON-LD Linked Data proof.",
            "properties": {
              "type": {
                "type": "string",
                "description": "Linked Data Signature Suite used to produce proof."
              },
              "created": {
                "type": "string",
                "description": "Date the proof was created."
              },
              "challenge": {
                "type": "string",
                "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
              },
              "domain": {
                "type": "string",
                "description": "The domain of the proof to restrict its use to a particular target."
              },
              "nonce": {
                "type": "string",
                "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
              },
              "verificationMethod": {
                "type": "string",
                "description": "Verification Method used to verify proof."
              },
              "proofPurpose": {
                "type": "string",
                "description": "The purpose of the proof to be used with verificationMethod."
              },
              "jws": {
                "type": "string",
                "description": "Detached JSON Web Signature."
              },
              "proofValue": {
                "type": "string",
                "description": "Value of the Linked Data proof."
              }
            },
            "example": {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
            }
          }
        }
      }
    ],
    "example": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "id": "http://example.gov/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": "did:example:123",
      "issuanceDate": "2020-03-16T22:37:26.544Z",
      "credentialSubject": {
        "id": "did:example:123",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      },
      "proof": {
        "type": "Ed25519Signature2018",
        "created": "2020-04-02T18:28:08Z",
        "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
        "proofPurpose": "assertionMethod",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
      }
    }
  },
  "options": {
    "type": "object",
    "additionalProperties": false,
    "description": "Options for specifying how the LinkedDataProof is verified.",
    "properties": {
      "challenge": {
        "type": "string",
        "description": "A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2"
      },
      "domain": {
        "type": "string",
        "description": "The intended domain of validity for the proof. For example website.example"
      }
    },
    "example": {
      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
      "proofPurpose": "assertionMethod",
      "created": "2020-04-02T18:48:36Z",
      "domain": "example.com",
      "challenge": "d436f0c8-fbd9-4e48-bbb2-55fc5d0920a8"
    }
  }
}

3.3.2 Verify Presentation

POST /presentations/verify - Verifies a Presentation with or without proofs attached and returns a verificationResult in the response body.

ResponseDescription
200Verifiable Presentation successfully verified!
400Invalid or malformed input
413Payload too large
429Request rate limit exceeded.
500Internal Server Error

The /presentations/verify endpoint uses the following schema when receiving a POST:

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "verifiablePresentation": {
          "type": "object",
          "description": "A JSON-LD Verifiable Presentation with a proof.",
          "allOf": [
            {
              "type": "object",
              "description": "A JSON-LD Verifiable Presentation without a proof.",
              "properties": {
                "@context": {
                  "type": "array",
                  "description": "The JSON-LD context of the presentation.",
                  "items": {
                    "type": "string"
                  }
                },
                "id": {
                  "type": "string",
                  "description": "The ID of the presentation."
                },
                "type": {
                  "type": "array",
                  "description": "The JSON-LD type of the presentation.",
                  "items": {
                    "type": "string"
                  }
                },
                "holder": {
                  "type": "object",
                  "description": "The holder - will be ignored if no proof is present since there is no proof of authority over the credentials",
                  "nullable": true
                },
                "verifiableCredential": {
                  "type": "array",
                  "description": "The Verifiable Credentials",
                  "items": {
                    "type": "object",
                    "description": "A JSON-LD Verifiable Credential with a proof.",
                    "allOf": [
                      {
                        "type": "object",
                        "description": "A JSON-LD Verifiable Credential without a proof.",
                        "properties": {
                          "@context": {
                            "type": "array",
                            "description": "The JSON-LD context of the credential.",
                            "items": {
                              "type": "string"
                            }
                          },
                          "id": {
                            "type": "string",
                            "description": "The ID of the credential."
                          },
                          "type": {
                            "type": "array",
                            "description": "The JSON-LD type of the credential.",
                            "items": {
                              "type": "string"
                            }
                          },
                          "issuer": {
                            "type": "object",
                            "description": "A JSON-LD Verifiable Credential Issuer.",
                            "oneOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  }
                                }
                              }
                            ],
                            "example": {
                              "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
                            }
                          },
                          "issuanceDate": {
                            "type": "string",
                            "description": "The issuanceDate"
                          },
                          "expirationDate": {
                            "type": "string",
                            "description": "The expirationDate"
                          },
                          "credentialSubject": {
                            "type": "object",
                            "description": "The subject"
                          }
                        },
                        "example": {
                          "@context": [
                            "https://www.w3.org/2018/credentials/v1",
                            "https://www.w3.org/2018/credentials/examples/v1"
                          ],
                          "id": "http://example.gov/credentials/3732",
                          "type": [
                            "VerifiableCredential",
                            "UniversityDegreeCredential"
                          ],
                          "issuer": "did:example:123",
                          "issuanceDate": "2020-03-16T22:37:26.544Z",
                          "credentialSubject": {
                            "id": "did:example:123",
                            "degree": {
                              "type": "BachelorDegree",
                              "name": "Bachelor of Science and Arts"
                            }
                          }
                        }
                      },
                      {
                        "type": "object",
                        "properties": {
                          "proof": {
                            "type": "object",
                            "description": "A JSON-LD Linked Data proof.",
                            "properties": {
                              "type": {
                                "type": "string",
                                "description": "Linked Data Signature Suite used to produce proof."
                              },
                              "created": {
                                "type": "string",
                                "description": "Date the proof was created."
                              },
                              "challenge": {
                                "type": "string",
                                "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
                              },
                              "domain": {
                                "type": "string",
                                "description": "The domain of the proof to restrict its use to a particular target."
                              },
                              "nonce": {
                                "type": "string",
                                "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
                              },
                              "verificationMethod": {
                                "type": "string",
                                "description": "Verification Method used to verify proof."
                              },
                              "proofPurpose": {
                                "type": "string",
                                "description": "The purpose of the proof to be used with verificationMethod."
                              },
                              "jws": {
                                "type": "string",
                                "description": "Detached JSON Web Signature."
                              },
                              "proofValue": {
                                "type": "string",
                                "description": "Value of the Linked Data proof."
                              }
                            },
                            "example": {
                              "type": "Ed25519Signature2018",
                              "created": "2020-04-02T18:28:08Z",
                              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                              "proofPurpose": "assertionMethod",
                              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                            }
                          }
                        }
                      }
                    ],
                    "example": {
                      "@context": [
                        "https://www.w3.org/2018/credentials/v1",
                        "https://www.w3.org/2018/credentials/examples/v1"
                      ],
                      "id": "http://example.gov/credentials/3732",
                      "type": [
                        "VerifiableCredential",
                        "UniversityDegreeCredential"
                      ],
                      "issuer": "did:example:123",
                      "issuanceDate": "2020-03-16T22:37:26.544Z",
                      "credentialSubject": {
                        "id": "did:example:123",
                        "degree": {
                          "type": "BachelorDegree",
                          "name": "Bachelor of Science and Arts"
                        }
                      },
                      "proof": {
                        "type": "Ed25519Signature2018",
                        "created": "2020-04-02T18:28:08Z",
                        "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                        "proofPurpose": "assertionMethod",
                        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                      }
                    }
                  }
                }
              },
              "example": {
                "@context": [
                  "https://www.w3.org/2018/credentials/v1",
                  "https://www.w3.org/2018/credentials/examples/v1"
                ],
                "holder": "did:example:123",
                "type": "VerifiablePresentation",
                "verifiableCredential": [
                  {
                    "@context": [
                      "https://www.w3.org/2018/credentials/v1",
                      "https://www.w3.org/2018/credentials/examples/v1"
                    ]
                  },
                  {
                    "id": "http://example.gov/credentials/3732"
                  },
                  {
                    "type": [
                      "VerifiableCredential",
                      "UniversityDegreeCredential"
                    ]
                  },
                  {
                    "issuer": "did:example:123"
                  },
                  {
                    "issuanceDate": "2020-03-16T22:37:26.544Z"
                  },
                  {
                    "credentialSubject": {
                      "id": "did:example:123",
                      "degree": {
                        "type": "BachelorDegree",
                        "name": "Bachelor of Science and Arts"
                      }
                    }
                  },
                  {
                    "proof": {
                      "type": "Ed25519Signature2018",
                      "created": "2020-04-02T18:28:08Z",
                      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                      "proofPurpose": "assertionMethod",
                      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                    }
                  }
                ]
              }
            },
            {
              "type": "object",
              "properties": {
                "proof": {
                  "type": "object",
                  "description": "A JSON-LD Linked Data proof.",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Linked Data Signature Suite used to produce proof."
                    },
                    "created": {
                      "type": "string",
                      "description": "Date the proof was created."
                    },
                    "challenge": {
                      "type": "string",
                      "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
                    },
                    "domain": {
                      "type": "string",
                      "description": "The domain of the proof to restrict its use to a particular target."
                    },
                    "nonce": {
                      "type": "string",
                      "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
                    },
                    "verificationMethod": {
                      "type": "string",
                      "description": "Verification Method used to verify proof."
                    },
                    "proofPurpose": {
                      "type": "string",
                      "description": "The purpose of the proof to be used with verificationMethod."
                    },
                    "jws": {
                      "type": "string",
                      "description": "Detached JSON Web Signature."
                    },
                    "proofValue": {
                      "type": "string",
                      "description": "Value of the Linked Data proof."
                    }
                  },
                  "example": {
                    "type": "Ed25519Signature2018",
                    "created": "2020-04-02T18:28:08Z",
                    "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                    "proofPurpose": "assertionMethod",
                    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                  }
                }
              }
            }
          ],
          "example": {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "holder": "did:example:123",
            "type": "VerifiablePresentation",
            "verifiableCredential": [
              {
                "@context": [
                  "https://www.w3.org/2018/credentials/v1",
                  "https://www.w3.org/2018/credentials/examples/v1"
                ]
              },
              {
                "id": "http://example.gov/credentials/3732"
              },
              {
                "type": [
                  "VerifiableCredential",
                  "UniversityDegreeCredential"
                ]
              },
              {
                "issuer": "did:example:123"
              },
              {
                "issuanceDate": "2020-03-16T22:37:26.544Z"
              },
              {
                "credentialSubject": {
                  "id": "did:example:123",
                  "degree": {
                    "type": "BachelorDegree",
                    "name": "Bachelor of Science and Arts"
                  }
                }
              },
              {
                "proof": {
                  "type": "Ed25519Signature2018",
                  "created": "2020-04-02T18:28:08Z",
                  "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                  "proofPurpose": "assertionMethod",
                  "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                }
              }
            ],
            "proof": {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
            }
          }
        },
        "options": {
          "type": "object",
          "additionalProperties": false,
          "description": "Options for specifying how the LinkedDataProof is verified.",
          "properties": {
            "challenge": {
              "type": "string",
              "description": "A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2"
            },
            "domain": {
              "type": "string",
              "description": "The intended domain of validity for the proof. For example website.example"
            }
          },
          "example": {
            "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
            "proofPurpose": "assertionMethod",
            "created": "2020-04-02T18:48:36Z",
            "domain": "example.com",
            "challenge": "d436f0c8-fbd9-4e48-bbb2-55fc5d0920a8"
          }
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "presentation": {
          "type": "object",
          "description": "A JSON-LD Verifiable Presentation without a proof.",
          "properties": {
            "@context": {
              "type": "array",
              "description": "The JSON-LD context of the presentation.",
              "items": {
                "type": "string"
              }
            },
            "id": {
              "type": "string",
              "description": "The ID of the presentation."
            },
            "type": {
              "type": "array",
              "description": "The JSON-LD type of the presentation.",
              "items": {
                "type": "string"
              }
            },
            "holder": {
              "type": "object",
              "description": "The holder - will be ignored if no proof is present since there is no proof of authority over the credentials",
              "nullable": true
            },
            "verifiableCredential": {
              "type": "array",
              "description": "The Verifiable Credentials",
              "items": {
                "type": "object",
                "description": "A JSON-LD Verifiable Credential with a proof.",
                "allOf": [
                  {
                    "type": "object",
                    "description": "A JSON-LD Verifiable Credential without a proof.",
                    "properties": {
                      "@context": {
                        "type": "array",
                        "description": "The JSON-LD context of the credential.",
                        "items": {
                          "type": "string"
                        }
                      },
                      "id": {
                        "type": "string",
                        "description": "The ID of the credential."
                      },
                      "type": {
                        "type": "array",
                        "description": "The JSON-LD type of the credential.",
                        "items": {
                          "type": "string"
                        }
                      },
                      "issuer": {
                        "type": "object",
                        "description": "A JSON-LD Verifiable Credential Issuer.",
                        "oneOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              }
                            }
                          }
                        ],
                        "example": {
                          "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
                        }
                      },
                      "issuanceDate": {
                        "type": "string",
                        "description": "The issuanceDate"
                      },
                      "expirationDate": {
                        "type": "string",
                        "description": "The expirationDate"
                      },
                      "credentialSubject": {
                        "type": "object",
                        "description": "The subject"
                      }
                    },
                    "example": {
                      "@context": [
                        "https://www.w3.org/2018/credentials/v1",
                        "https://www.w3.org/2018/credentials/examples/v1"
                      ],
                      "id": "http://example.gov/credentials/3732",
                      "type": [
                        "VerifiableCredential",
                        "UniversityDegreeCredential"
                      ],
                      "issuer": "did:example:123",
                      "issuanceDate": "2020-03-16T22:37:26.544Z",
                      "credentialSubject": {
                        "id": "did:example:123",
                        "degree": {
                          "type": "BachelorDegree",
                          "name": "Bachelor of Science and Arts"
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "properties": {
                      "proof": {
                        "type": "object",
                        "description": "A JSON-LD Linked Data proof.",
                        "properties": {
                          "type": {
                            "type": "string",
                            "description": "Linked Data Signature Suite used to produce proof."
                          },
                          "created": {
                            "type": "string",
                            "description": "Date the proof was created."
                          },
                          "challenge": {
                            "type": "string",
                            "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
                          },
                          "domain": {
                            "type": "string",
                            "description": "The domain of the proof to restrict its use to a particular target."
                          },
                          "nonce": {
                            "type": "string",
                            "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
                          },
                          "verificationMethod": {
                            "type": "string",
                            "description": "Verification Method used to verify proof."
                          },
                          "proofPurpose": {
                            "type": "string",
                            "description": "The purpose of the proof to be used with verificationMethod."
                          },
                          "jws": {
                            "type": "string",
                            "description": "Detached JSON Web Signature."
                          },
                          "proofValue": {
                            "type": "string",
                            "description": "Value of the Linked Data proof."
                          }
                        },
                        "example": {
                          "type": "Ed25519Signature2018",
                          "created": "2020-04-02T18:28:08Z",
                          "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                          "proofPurpose": "assertionMethod",
                          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                        }
                      }
                    }
                  }
                ],
                "example": {
                  "@context": [
                    "https://www.w3.org/2018/credentials/v1",
                    "https://www.w3.org/2018/credentials/examples/v1"
                  ],
                  "id": "http://example.gov/credentials/3732",
                  "type": [
                    "VerifiableCredential",
                    "UniversityDegreeCredential"
                  ],
                  "issuer": "did:example:123",
                  "issuanceDate": "2020-03-16T22:37:26.544Z",
                  "credentialSubject": {
                    "id": "did:example:123",
                    "degree": {
                      "type": "BachelorDegree",
                      "name": "Bachelor of Science and Arts"
                    }
                  },
                  "proof": {
                    "type": "Ed25519Signature2018",
                    "created": "2020-04-02T18:28:08Z",
                    "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                    "proofPurpose": "assertionMethod",
                    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                  }
                }
              }
            }
          },
          "example": {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "holder": "did:example:123",
            "type": "VerifiablePresentation",
            "verifiableCredential": [
              {
                "@context": [
                  "https://www.w3.org/2018/credentials/v1",
                  "https://www.w3.org/2018/credentials/examples/v1"
                ]
              },
              {
                "id": "http://example.gov/credentials/3732"
              },
              {
                "type": [
                  "VerifiableCredential",
                  "UniversityDegreeCredential"
                ]
              },
              {
                "issuer": "did:example:123"
              },
              {
                "issuanceDate": "2020-03-16T22:37:26.544Z"
              },
              {
                "credentialSubject": {
                  "id": "did:example:123",
                  "degree": {
                    "type": "BachelorDegree",
                    "name": "Bachelor of Science and Arts"
                  }
                }
              },
              {
                "proof": {
                  "type": "Ed25519Signature2018",
                  "created": "2020-04-02T18:28:08Z",
                  "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                  "proofPurpose": "assertionMethod",
                  "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

3.4 Presenting

The following APIs are defined for presenting a Verifiable Credential:

EndpointDescription
POST /credentials/deriveDerives a credential and returns it in the response body.
POST /presentations/proveProves a presentation and returns it in the response body.
POST /presentations/availableNotifies a holder of an available presentation.
POST /presentations/submissionsProvide a presentation for a holder to store.

3.4.1 Derive Credential

POST /credentials/derive - Derives a credential and returns it in the response body.

ResponseDescription
201Credential derived successfully.
400Invalid Request
500Internal Error
501Not Implemented

The /credentials/derive endpoint uses the following schema when receiving a POST:

{
  "verifiableCredential": {
    "type": "object",
    "description": "A JSON-LD Verifiable Credential with a proof.",
    "allOf": [
      {
        "type": "object",
        "description": "A JSON-LD Verifiable Credential without a proof.",
        "properties": {
          "@context": {
            "type": "array",
            "description": "The JSON-LD context of the credential.",
            "items": {
              "type": "string"
            }
          },
          "id": {
            "type": "string",
            "description": "The ID of the credential."
          },
          "type": {
            "type": "array",
            "description": "The JSON-LD type of the credential.",
            "items": {
              "type": "string"
            }
          },
          "issuer": {
            "type": "object",
            "description": "A JSON-LD Verifiable Credential Issuer.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  }
                }
              }
            ],
            "example": {
              "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
            }
          },
          "issuanceDate": {
            "type": "string",
            "description": "The issuanceDate"
          },
          "expirationDate": {
            "type": "string",
            "description": "The expirationDate"
          },
          "credentialSubject": {
            "type": "object",
            "description": "The subject"
          }
        },
        "example": {
          "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://www.w3.org/2018/credentials/examples/v1"
          ],
          "id": "http://example.gov/credentials/3732",
          "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
          ],
          "issuer": "did:example:123",
          "issuanceDate": "2020-03-16T22:37:26.544Z",
          "credentialSubject": {
            "id": "did:example:123",
            "degree": {
              "type": "BachelorDegree",
              "name": "Bachelor of Science and Arts"
            }
          }
        }
      },
      {
        "type": "object",
        "properties": {
          "proof": {
            "type": "object",
            "description": "A JSON-LD Linked Data proof.",
            "properties": {
              "type": {
                "type": "string",
                "description": "Linked Data Signature Suite used to produce proof."
              },
              "created": {
                "type": "string",
                "description": "Date the proof was created."
              },
              "challenge": {
                "type": "string",
                "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
              },
              "domain": {
                "type": "string",
                "description": "The domain of the proof to restrict its use to a particular target."
              },
              "nonce": {
                "type": "string",
                "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
              },
              "verificationMethod": {
                "type": "string",
                "description": "Verification Method used to verify proof."
              },
              "proofPurpose": {
                "type": "string",
                "description": "The purpose of the proof to be used with verificationMethod."
              },
              "jws": {
                "type": "string",
                "description": "Detached JSON Web Signature."
              },
              "proofValue": {
                "type": "string",
                "description": "Value of the Linked Data proof."
              }
            },
            "example": {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
            }
          }
        }
      }
    ],
    "example": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "id": "http://example.gov/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": "did:example:123",
      "issuanceDate": "2020-03-16T22:37:26.544Z",
      "credentialSubject": {
        "id": "did:example:123",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      },
      "proof": {
        "type": "Ed25519Signature2018",
        "created": "2020-04-02T18:28:08Z",
        "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
        "proofPurpose": "assertionMethod",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
      }
    }
  },
  "frame": {
    "type": "object",
    "description": "A JSON-LD frame used for selective disclosure."
  },
  "options": {
    "type": "object",
    "additionalProperties": false,
    "description": "Options for specifying how the derived credential is created.",
    "properties": {
      "nonce": {
        "type": "string",
        "description": "An encoded nonce provided by the holder of the credential to be included into the LinkedDataProof."
      }
    },
    "example": {
      "nonce": "lEixQKDQvRecCifKl789TQj+Ii6YWDLSwn3AxR0VpPJ1QV5htod/0VCchVf1zVM0y2E="
    }
  }
}

3.4.2 Prove Presentation

POST /presentations/prove - Proves a presentation and returns it in the response body.

ResponseDescription
201Presentation successfully proved!
400invalid input!
500error!

The /presentations/prove endpoint uses the following schema when receiving a POST:

{
  "presentation": {
    "type": "object",
    "description": "A JSON-LD Verifiable Presentation without a proof.",
    "properties": {
      "@context": {
        "type": "array",
        "description": "The JSON-LD context of the presentation.",
        "items": {
          "type": "string"
        }
      },
      "id": {
        "type": "string",
        "description": "The ID of the presentation."
      },
      "type": {
        "type": "array",
        "description": "The JSON-LD type of the presentation.",
        "items": {
          "type": "string"
        }
      },
      "holder": {
        "type": "object",
        "description": "The holder - will be ignored if no proof is present since there is no proof of authority over the credentials",
        "nullable": true
      },
      "verifiableCredential": {
        "type": "array",
        "description": "The Verifiable Credentials",
        "items": {
          "type": "object",
          "description": "A JSON-LD Verifiable Credential with a proof.",
          "allOf": [
            {
              "type": "object",
              "description": "A JSON-LD Verifiable Credential without a proof.",
              "properties": {
                "@context": {
                  "type": "array",
                  "description": "The JSON-LD context of the credential.",
                  "items": {
                    "type": "string"
                  }
                },
                "id": {
                  "type": "string",
                  "description": "The ID of the credential."
                },
                "type": {
                  "type": "array",
                  "description": "The JSON-LD type of the credential.",
                  "items": {
                    "type": "string"
                  }
                },
                "issuer": {
                  "type": "object",
                  "description": "A JSON-LD Verifiable Credential Issuer.",
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        }
                      }
                    }
                  ],
                  "example": {
                    "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
                  }
                },
                "issuanceDate": {
                  "type": "string",
                  "description": "The issuanceDate"
                },
                "expirationDate": {
                  "type": "string",
                  "description": "The expirationDate"
                },
                "credentialSubject": {
                  "type": "object",
                  "description": "The subject"
                }
              },
              "example": {
                "@context": [
                  "https://www.w3.org/2018/credentials/v1",
                  "https://www.w3.org/2018/credentials/examples/v1"
                ],
                "id": "http://example.gov/credentials/3732",
                "type": [
                  "VerifiableCredential",
                  "UniversityDegreeCredential"
                ],
                "issuer": "did:example:123",
                "issuanceDate": "2020-03-16T22:37:26.544Z",
                "credentialSubject": {
                  "id": "did:example:123",
                  "degree": {
                    "type": "BachelorDegree",
                    "name": "Bachelor of Science and Arts"
                  }
                }
              }
            },
            {
              "type": "object",
              "properties": {
                "proof": {
                  "type": "object",
                  "description": "A JSON-LD Linked Data proof.",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Linked Data Signature Suite used to produce proof."
                    },
                    "created": {
                      "type": "string",
                      "description": "Date the proof was created."
                    },
                    "challenge": {
                      "type": "string",
                      "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
                    },
                    "domain": {
                      "type": "string",
                      "description": "The domain of the proof to restrict its use to a particular target."
                    },
                    "nonce": {
                      "type": "string",
                      "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
                    },
                    "verificationMethod": {
                      "type": "string",
                      "description": "Verification Method used to verify proof."
                    },
                    "proofPurpose": {
                      "type": "string",
                      "description": "The purpose of the proof to be used with verificationMethod."
                    },
                    "jws": {
                      "type": "string",
                      "description": "Detached JSON Web Signature."
                    },
                    "proofValue": {
                      "type": "string",
                      "description": "Value of the Linked Data proof."
                    }
                  },
                  "example": {
                    "type": "Ed25519Signature2018",
                    "created": "2020-04-02T18:28:08Z",
                    "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                    "proofPurpose": "assertionMethod",
                    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                  }
                }
              }
            }
          ],
          "example": {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "id": "http://example.gov/credentials/3732",
            "type": [
              "VerifiableCredential",
              "UniversityDegreeCredential"
            ],
            "issuer": "did:example:123",
            "issuanceDate": "2020-03-16T22:37:26.544Z",
            "credentialSubject": {
              "id": "did:example:123",
              "degree": {
                "type": "BachelorDegree",
                "name": "Bachelor of Science and Arts"
              }
            },
            "proof": {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
            }
          }
        }
      }
    },
    "example": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "holder": "did:example:123",
      "type": "VerifiablePresentation",
      "verifiableCredential": [
        {
          "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://www.w3.org/2018/credentials/examples/v1"
          ]
        },
        {
          "id": "http://example.gov/credentials/3732"
        },
        {
          "type": [
            "VerifiableCredential",
            "UniversityDegreeCredential"
          ]
        },
        {
          "issuer": "did:example:123"
        },
        {
          "issuanceDate": "2020-03-16T22:37:26.544Z"
        },
        {
          "credentialSubject": {
            "id": "did:example:123",
            "degree": {
              "type": "BachelorDegree",
              "name": "Bachelor of Science and Arts"
            }
          }
        },
        {
          "proof": {
            "type": "Ed25519Signature2018",
            "created": "2020-04-02T18:28:08Z",
            "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
            "proofPurpose": "assertionMethod",
            "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
          }
        }
      ]
    }
  },
  "options": {
    "type": "object",
    "additionalProperties": false,
    "description": "Options for specifying how the LinkedDataProof is created.",
    "properties": {
      "type": {
        "type": "string",
        "description": "The type of the proof. Default is an appropriate proof type corresponding to the verification method."
      },
      "verificationMethod": {
        "type": "string",
        "description": "The URI of the verificationMethod used for the proof. If omitted, a default verification method will be used."
      },
      "proofPurpose": {
        "type": "string",
        "description": "The purpose of the proof. Default 'assertionMethod'."
      },
      "created": {
        "type": "string",
        "description": "The date and time of the proof (with a maximum accuracy in seconds). Default current system time."
      },
      "challenge": {
        "type": "string",
        "description": "A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2"
      },
      "domain": {
        "type": "string",
        "description": "The intended domain of validity for the proof. For example website.example"
      }
    },
    "example": {
      "type": "Ed25519Signature2018",
      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
      "proofPurpose": "assertionMethod",
      "created": "2020-04-02T18:48:36Z",
      "domain": "example.com",
      "challenge": "d436f0c8-fbd9-4e48-bbb2-55fc5d0920a8"
    }
  }
}

3.4.3 Presentation Availability

POST /presentations/available - Notifies a holder of an available presentation.

ResponseDescription
200Proceed with presentation
400Request for presentation is malformed
500internal error
501Not implemented

The /presentations/available endpoint uses the following schema when receiving a POST:

{
  "query": {
    "type": "object",
    "description": "See https://w3c-ccg.github.io/vp-request-spec/#format",
    "properties": {
      "type": {
        "type": "string",
        "description": "The type of query the server should reply with."
      },
      "credentialQuery": {
        "type": "object",
        "description": "Details of the client's available presentation"
      }
    }
  }
}

3.4.4 Submit Presentation

POST /presentations/submissions - Provide a presentation for a holder to store.

ResponseDescription
202Presentation accepted
400Presentation is malformed
401Presentation did not contain a proof
402Payment required
403Presentation verification failed
425Server is unwilling to risk processing a request that might be replayed
500internal error
501Not implemented

The /presentations/submissions endpoint uses the following schema when receiving a POST:

{
  "type": "object",
  "description": "A JSON-LD Verifiable Presentation with a proof.",
  "allOf": [
    {
      "type": "object",
      "description": "A JSON-LD Verifiable Presentation without a proof.",
      "properties": {
        "@context": {
          "type": "array",
          "description": "The JSON-LD context of the presentation.",
          "items": {
            "type": "string"
          }
        },
        "id": {
          "type": "string",
          "description": "The ID of the presentation."
        },
        "type": {
          "type": "array",
          "description": "The JSON-LD type of the presentation.",
          "items": {
            "type": "string"
          }
        },
        "holder": {
          "type": "object",
          "description": "The holder - will be ignored if no proof is present since there is no proof of authority over the credentials",
          "nullable": true
        },
        "verifiableCredential": {
          "type": "array",
          "description": "The Verifiable Credentials",
          "items": {
            "type": "object",
            "description": "A JSON-LD Verifiable Credential with a proof.",
            "allOf": [
              {
                "type": "object",
                "description": "A JSON-LD Verifiable Credential without a proof.",
                "properties": {
                  "@context": {
                    "type": "array",
                    "description": "The JSON-LD context of the credential.",
                    "items": {
                      "type": "string"
                    }
                  },
                  "id": {
                    "type": "string",
                    "description": "The ID of the credential."
                  },
                  "type": {
                    "type": "array",
                    "description": "The JSON-LD type of the credential.",
                    "items": {
                      "type": "string"
                    }
                  },
                  "issuer": {
                    "type": "object",
                    "description": "A JSON-LD Verifiable Credential Issuer.",
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          }
                        }
                      }
                    ],
                    "example": {
                      "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
                    }
                  },
                  "issuanceDate": {
                    "type": "string",
                    "description": "The issuanceDate"
                  },
                  "expirationDate": {
                    "type": "string",
                    "description": "The expirationDate"
                  },
                  "credentialSubject": {
                    "type": "object",
                    "description": "The subject"
                  }
                },
                "example": {
                  "@context": [
                    "https://www.w3.org/2018/credentials/v1",
                    "https://www.w3.org/2018/credentials/examples/v1"
                  ],
                  "id": "http://example.gov/credentials/3732",
                  "type": [
                    "VerifiableCredential",
                    "UniversityDegreeCredential"
                  ],
                  "issuer": "did:example:123",
                  "issuanceDate": "2020-03-16T22:37:26.544Z",
                  "credentialSubject": {
                    "id": "did:example:123",
                    "degree": {
                      "type": "BachelorDegree",
                      "name": "Bachelor of Science and Arts"
                    }
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "proof": {
                    "type": "object",
                    "description": "A JSON-LD Linked Data proof.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "description": "Linked Data Signature Suite used to produce proof."
                      },
                      "created": {
                        "type": "string",
                        "description": "Date the proof was created."
                      },
                      "challenge": {
                        "type": "string",
                        "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
                      },
                      "domain": {
                        "type": "string",
                        "description": "The domain of the proof to restrict its use to a particular target."
                      },
                      "nonce": {
                        "type": "string",
                        "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
                      },
                      "verificationMethod": {
                        "type": "string",
                        "description": "Verification Method used to verify proof."
                      },
                      "proofPurpose": {
                        "type": "string",
                        "description": "The purpose of the proof to be used with verificationMethod."
                      },
                      "jws": {
                        "type": "string",
                        "description": "Detached JSON Web Signature."
                      },
                      "proofValue": {
                        "type": "string",
                        "description": "Value of the Linked Data proof."
                      }
                    },
                    "example": {
                      "type": "Ed25519Signature2018",
                      "created": "2020-04-02T18:28:08Z",
                      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                      "proofPurpose": "assertionMethod",
                      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                    }
                  }
                }
              }
            ],
            "example": {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://www.w3.org/2018/credentials/examples/v1"
              ],
              "id": "http://example.gov/credentials/3732",
              "type": [
                "VerifiableCredential",
                "UniversityDegreeCredential"
              ],
              "issuer": "did:example:123",
              "issuanceDate": "2020-03-16T22:37:26.544Z",
              "credentialSubject": {
                "id": "did:example:123",
                "degree": {
                  "type": "BachelorDegree",
                  "name": "Bachelor of Science and Arts"
                }
              },
              "proof": {
                "type": "Ed25519Signature2018",
                "created": "2020-04-02T18:28:08Z",
                "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                "proofPurpose": "assertionMethod",
                "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
              }
            }
          }
        }
      },
      "example": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://www.w3.org/2018/credentials/examples/v1"
        ],
        "holder": "did:example:123",
        "type": "VerifiablePresentation",
        "verifiableCredential": [
          {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ]
          },
          {
            "id": "http://example.gov/credentials/3732"
          },
          {
            "type": [
              "VerifiableCredential",
              "UniversityDegreeCredential"
            ]
          },
          {
            "issuer": "did:example:123"
          },
          {
            "issuanceDate": "2020-03-16T22:37:26.544Z"
          },
          {
            "credentialSubject": {
              "id": "did:example:123",
              "degree": {
                "type": "BachelorDegree",
                "name": "Bachelor of Science and Arts"
              }
            }
          },
          {
            "proof": {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
            }
          }
        ]
      }
    },
    {
      "type": "object",
      "properties": {
        "proof": {
          "type": "object",
          "description": "A JSON-LD Linked Data proof.",
          "properties": {
            "type": {
              "type": "string",
              "description": "Linked Data Signature Suite used to produce proof."
            },
            "created": {
              "type": "string",
              "description": "Date the proof was created."
            },
            "challenge": {
              "type": "string",
              "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
            },
            "domain": {
              "type": "string",
              "description": "The domain of the proof to restrict its use to a particular target."
            },
            "nonce": {
              "type": "string",
              "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
            },
            "verificationMethod": {
              "type": "string",
              "description": "Verification Method used to verify proof."
            },
            "proofPurpose": {
              "type": "string",
              "description": "The purpose of the proof to be used with verificationMethod."
            },
            "jws": {
              "type": "string",
              "description": "Detached JSON Web Signature."
            },
            "proofValue": {
              "type": "string",
              "description": "Value of the Linked Data proof."
            }
          },
          "example": {
            "type": "Ed25519Signature2018",
            "created": "2020-04-02T18:28:08Z",
            "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
            "proofPurpose": "assertionMethod",
            "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
          }
        }
      }
    }
  ],
  "example": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "holder": "did:example:123",
    "type": "VerifiablePresentation",
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://www.w3.org/2018/credentials/examples/v1"
        ]
      },
      {
        "id": "http://example.gov/credentials/3732"
      },
      {
        "type": [
          "VerifiableCredential",
          "UniversityDegreeCredential"
        ]
      },
      {
        "issuer": "did:example:123"
      },
      {
        "issuanceDate": "2020-03-16T22:37:26.544Z"
      },
      {
        "credentialSubject": {
          "id": "did:example:123",
          "degree": {
            "type": "BachelorDegree",
            "name": "Bachelor of Science and Arts"
          }
        }
      },
      {
        "proof": {
          "type": "Ed25519Signature2018",
          "created": "2020-04-02T18:28:08Z",
          "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
          "proofPurpose": "assertionMethod",
          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
        }
      }
    ],
    "proof": {
      "type": "Ed25519Signature2018",
      "created": "2020-04-02T18:28:08Z",
      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
      "proofPurpose": "assertionMethod",
      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
    }
  }
}

3.5 Workflows

The following APIs are defined for executing Verifiable Credential workflows.

EndpointDescription
POST /workflows/{name}/startStart a workflow.
POST /workflows/{id}/presentationsPresent information to an active workflow.
Issue 1: EXPERIMENTAL FEATURE

Workflows are an experimental feature that is currently being explored by the group. This feature is likely to undergo significant revision as conversations around the feature progress.

The APIs in this specification enables unmediated (automated, machine-to-machine) or mediated (person in the loop) workflows to be executed. These workflows are initiated by a Holder App and responded to by any App that implements workflows. The flows consist of the following steps:

  1. The Holder App contacts the receiving App to request the initiation of a particular workflow.
  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 workflow 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.

A diagram of the steps outlined above is presented below:

Note

The general workflow 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:

Example 1: Step 1 (request to issuer): Initiate degree refresh workflow 
POST /workflows/refresh-degree/start HTTP/1.1
Host: example.edu
Content-Type: application/json
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Example 2: Step 2 (response from issuer): Verifiable Presentation Request 
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/workflows/123456/presentations"
        }]
      }
    }
  }
}
Note: Interact service description

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.

Note

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.

Issue 2: Demonstrate usage of WACI/PeX?

We should make it clear that Issuers can choose to use one or more presentation request formats simultaneously in order to maximize the chances that a given client will be able to respond to a refresh workflow. This should probably be more clearly stated in the VC-API specification.

Example 3: Step 3 (presentation to issuer): Provide Verifiable Presentation 
POST /workflows/123456/presentations 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/workflows/refresh-degree/start",
      "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"
  }
}
Example 4: Step 4 (response from issuer): Re-issued Verifiable Credential 
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/workflows/refresh-degree/start",
      "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"
    }
  }]
}

3.5.1 Start Workflow

Issue 3: Generalize 'Presentation Availability' endpoint

The existing Presentation Availability endpoint requires a Verifiable Presentation to be submitted to the endpoint. The Start Workflow endpoint defined here generalizes the Presentation Availability endpoint by allowing arbitrary data to be posted to the endpoint. It is suggested that we can merge the API endpoint defined in this section with the Presentation Availability endpoint via the generalization provided in this section. The term "workflow" is a working title and is not intended to be the final feature name.

POST /workflows/{name}/start - Start a workflow.

ResponseDescription
201A new workflow was successfully created for the client.
400The workflow request was malformed.
500Internal Error
501Not implemented

The /workflows/{name}/start endpoint uses the following schema when receiving a POST:

{
  "oneOf": [
    {
      "type": "object"
    },
    {
      "type": "string"
    }
  ]
}

3.5.2 Workflow Interaction

Issue 4: Generalize 'Submit Presentation' endpoint

The existing Submit Presentation endpoint is highly similar to this endpoint and only differs in the return values provided by the endpoint. The Workflow Interaction endpoint defined here generalizes the Submit Presentation endpoint by allowing more variability in what is returned to the client and leaving some of the HTTP response codes undefined (which can be extended through other application-specific means). It is suggested that we can merge the API endpoint defined in this section with the Submit Presentation endpoint via the generalization provided in this section. The term "workflow" is a working title and is not intended to be the final feature name.

POST /workflows/{id}/presentations - Present information to an active workflow.

ResponseDescription
200Presentation was successful
201Presentation was received and a new workflow was successfully created for the client.
400Presentation is malformed
500Internal Server Error
501Not Implemented

The /workflows/{id}/presentations endpoint uses the following schema when receiving a POST:

{
  "type": "object",
  "description": "A JSON-LD Verifiable Presentation with a proof.",
  "allOf": [
    {
      "type": "object",
      "description": "A JSON-LD Verifiable Presentation without a proof.",
      "properties": {
        "@context": {
          "type": "array",
          "description": "The JSON-LD context of the presentation.",
          "items": {
            "type": "string"
          }
        },
        "id": {
          "type": "string",
          "description": "The ID of the presentation."
        },
        "type": {
          "type": "array",
          "description": "The JSON-LD type of the presentation.",
          "items": {
            "type": "string"
          }
        },
        "holder": {
          "type": "object",
          "description": "The holder - will be ignored if no proof is present since there is no proof of authority over the credentials",
          "nullable": true
        },
        "verifiableCredential": {
          "type": "array",
          "description": "The Verifiable Credentials",
          "items": {
            "type": "object",
            "description": "A JSON-LD Verifiable Credential with a proof.",
            "allOf": [
              {
                "type": "object",
                "description": "A JSON-LD Verifiable Credential without a proof.",
                "properties": {
                  "@context": {
                    "type": "array",
                    "description": "The JSON-LD context of the credential.",
                    "items": {
                      "type": "string"
                    }
                  },
                  "id": {
                    "type": "string",
                    "description": "The ID of the credential."
                  },
                  "type": {
                    "type": "array",
                    "description": "The JSON-LD type of the credential.",
                    "items": {
                      "type": "string"
                    }
                  },
                  "issuer": {
                    "type": "object",
                    "description": "A JSON-LD Verifiable Credential Issuer.",
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          }
                        }
                      }
                    ],
                    "example": {
                      "id": "did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd"
                    }
                  },
                  "issuanceDate": {
                    "type": "string",
                    "description": "The issuanceDate"
                  },
                  "expirationDate": {
                    "type": "string",
                    "description": "The expirationDate"
                  },
                  "credentialSubject": {
                    "type": "object",
                    "description": "The subject"
                  }
                },
                "example": {
                  "@context": [
                    "https://www.w3.org/2018/credentials/v1",
                    "https://www.w3.org/2018/credentials/examples/v1"
                  ],
                  "id": "http://example.gov/credentials/3732",
                  "type": [
                    "VerifiableCredential",
                    "UniversityDegreeCredential"
                  ],
                  "issuer": "did:example:123",
                  "issuanceDate": "2020-03-16T22:37:26.544Z",
                  "credentialSubject": {
                    "id": "did:example:123",
                    "degree": {
                      "type": "BachelorDegree",
                      "name": "Bachelor of Science and Arts"
                    }
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "proof": {
                    "type": "object",
                    "description": "A JSON-LD Linked Data proof.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "description": "Linked Data Signature Suite used to produce proof."
                      },
                      "created": {
                        "type": "string",
                        "description": "Date the proof was created."
                      },
                      "challenge": {
                        "type": "string",
                        "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
                      },
                      "domain": {
                        "type": "string",
                        "description": "The domain of the proof to restrict its use to a particular target."
                      },
                      "nonce": {
                        "type": "string",
                        "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
                      },
                      "verificationMethod": {
                        "type": "string",
                        "description": "Verification Method used to verify proof."
                      },
                      "proofPurpose": {
                        "type": "string",
                        "description": "The purpose of the proof to be used with verificationMethod."
                      },
                      "jws": {
                        "type": "string",
                        "description": "Detached JSON Web Signature."
                      },
                      "proofValue": {
                        "type": "string",
                        "description": "Value of the Linked Data proof."
                      }
                    },
                    "example": {
                      "type": "Ed25519Signature2018",
                      "created": "2020-04-02T18:28:08Z",
                      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                      "proofPurpose": "assertionMethod",
                      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
                    }
                  }
                }
              }
            ],
            "example": {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://www.w3.org/2018/credentials/examples/v1"
              ],
              "id": "http://example.gov/credentials/3732",
              "type": [
                "VerifiableCredential",
                "UniversityDegreeCredential"
              ],
              "issuer": "did:example:123",
              "issuanceDate": "2020-03-16T22:37:26.544Z",
              "credentialSubject": {
                "id": "did:example:123",
                "degree": {
                  "type": "BachelorDegree",
                  "name": "Bachelor of Science and Arts"
                }
              },
              "proof": {
                "type": "Ed25519Signature2018",
                "created": "2020-04-02T18:28:08Z",
                "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
                "proofPurpose": "assertionMethod",
                "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
              }
            }
          }
        }
      },
      "example": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://www.w3.org/2018/credentials/examples/v1"
        ],
        "holder": "did:example:123",
        "type": "VerifiablePresentation",
        "verifiableCredential": [
          {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ]
          },
          {
            "id": "http://example.gov/credentials/3732"
          },
          {
            "type": [
              "VerifiableCredential",
              "UniversityDegreeCredential"
            ]
          },
          {
            "issuer": "did:example:123"
          },
          {
            "issuanceDate": "2020-03-16T22:37:26.544Z"
          },
          {
            "credentialSubject": {
              "id": "did:example:123",
              "degree": {
                "type": "BachelorDegree",
                "name": "Bachelor of Science and Arts"
              }
            }
          },
          {
            "proof": {
              "type": "Ed25519Signature2018",
              "created": "2020-04-02T18:28:08Z",
              "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
              "proofPurpose": "assertionMethod",
              "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
            }
          }
        ]
      }
    },
    {
      "type": "object",
      "properties": {
        "proof": {
          "type": "object",
          "description": "A JSON-LD Linked Data proof.",
          "properties": {
            "type": {
              "type": "string",
              "description": "Linked Data Signature Suite used to produce proof."
            },
            "created": {
              "type": "string",
              "description": "Date the proof was created."
            },
            "challenge": {
              "type": "string",
              "description": "A value chosen by the verifier to mitigate authentication proof replay attacks."
            },
            "domain": {
              "type": "string",
              "description": "The domain of the proof to restrict its use to a particular target."
            },
            "nonce": {
              "type": "string",
              "description": "A value chosen by the creator of a proof to randomize proof values for privacy purposes."
            },
            "verificationMethod": {
              "type": "string",
              "description": "Verification Method used to verify proof."
            },
            "proofPurpose": {
              "type": "string",
              "description": "The purpose of the proof to be used with verificationMethod."
            },
            "jws": {
              "type": "string",
              "description": "Detached JSON Web Signature."
            },
            "proofValue": {
              "type": "string",
              "description": "Value of the Linked Data proof."
            }
          },
          "example": {
            "type": "Ed25519Signature2018",
            "created": "2020-04-02T18:28:08Z",
            "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
            "proofPurpose": "assertionMethod",
            "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
          }
        }
      }
    }
  ],
  "example": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "holder": "did:example:123",
    "type": "VerifiablePresentation",
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://www.w3.org/2018/credentials/examples/v1"
        ]
      },
      {
        "id": "http://example.gov/credentials/3732"
      },
      {
        "type": [
          "VerifiableCredential",
          "UniversityDegreeCredential"
        ]
      },
      {
        "issuer": "did:example:123"
      },
      {
        "issuanceDate": "2020-03-16T22:37:26.544Z"
      },
      {
        "credentialSubject": {
          "id": "did:example:123",
          "degree": {
            "type": "BachelorDegree",
            "name": "Bachelor of Science and Arts"
          }
        }
      },
      {
        "proof": {
          "type": "Ed25519Signature2018",
          "created": "2020-04-02T18:28:08Z",
          "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
          "proofPurpose": "assertionMethod",
          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
        }
      }
    ],
    "proof": {
      "type": "Ed25519Signature2018",
      "created": "2020-04-02T18:28:08Z",
      "verificationMethod": "did:example:123#z6MksHh7qHWvybLg5QTPPdG2DgEjjduBDArV9EF9mRiRzMBN",
      "proofPurpose": "assertionMethod",
      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YtqjEYnFENT7fNW-COD0HAACxeuQxPKAmp4nIl8jYAu__6IH2FpSxv81w-l5PvE1og50tS9tH8WyXMlXyo45CA"
    }
  }
}

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
[RFC6749]
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749
[RFC6750]
The OAuth 2.0 Authorization Framework: Bearer Token Usage. M. Jones; D. Hardt. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6750
[RFC7617]
The 'Basic' HTTP Authentication Scheme. J. Reschke. IETF. September 2015. Proposed Standard. URL: https://httpwg.org/specs/rfc7617.html
[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

[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/