Verifiable Credential API

VC-API is specification of a data model and HTTP protocols to issue, verify, present, and manage data in a Verifiable Credentials ecosystem.

Energy Web provides an implementation of VC-API to reduce difficulties for organizations to start issuing and verifying Verifiable Credentials. Using these APIs it becomes easy for anyone to do Proof of Concepts for SSI use cases.

VC-API can be easily integrated with existing systems and are configurable for complex exchanges. Implementers can choose to implement APIs that fits their use case. One can keep it simple with minimal set of APIs even for complex data exchanges (presentation).

Refer VC-API specification for more information.

Advantages of EW implementation of VC-API :

1. Portable, can be easily deployed to any environment and can be kept generic.

2. Easy integration and configuration.

3. Selective implementation of APIs based on the use case. For an application that provides feature to issue a credential only need to consume APIs specific to issuance.

4. Supports both Mediated and Unmediated exchange.

Entities of VC-API

The Verifiable Credentials data model introduces three actors Issuers, Holders and Verifier. VC-API defines components that these actors may use for credential issuance, verification and exchange.

Each actors can have their own set of components to participate in the credential exchange.

1. Coordinators : execute the business rules and policies set by the actors. Also acts as mediator between these actors.
2. Services : enable general VC-API functionality.
3. Status Service : facilitate publishing and checking of status of Verifiable Credentials.
4. Admin : responsible for configuring and managing all the other components.
5. Storage Services : provide mechanisms to store and manage Verifiable Credential of the associated actor.

Energy Web's implementation of VC-API only provides services which enable VC-API functionality. A developer can implement their own components that are mentioned above.

Use-case functionalities

Applications can perform authorisation, issuance, verification and presentation exchanges using VC-API.

1. Authorisation

Servers implementing VC-API can confirm clients to utilise authorisation mechanism when performing certain requests. The request APIs endpoint can specify whether authorisation is needed or not.

1. Issuance

For issuance of Verifiable Credentials, a holder can request any authority (Issuer) to issue a credential or can self-sign a credential.

1. Verification

A Holder can present their Verifiable Credential to the Verifier for verification. The Verifier can request the required credential from the holder using presentation-exchange protocol.

1. Presentation

The sharing / exchange of Verifiable Credentials happen through presentation. These exchanges are executed based on the exchange-definition that are configured at run time.

A general exchange flow would look like :

exchange-flow-diagram

Exchange Definition

The VC-API implementation can be easily deployed to any environment and can be kept generic, in other words exchanges are configured rather than coded in the application. This configuration is done at runtime via the use of Exchange Definitions.

In order to configure the credential exchange, you can use the exchange definition data transfer object. For reference see the Exchange Definition Data Transfer Object implemented by Energy Web.

Some different types of exchange definitions are :

Sample DIDAuth query VP Request

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

Sample PresentationDefinition query VP request

{
"exchangeId":"<SOME UNIQUE ID>",
    "query":[
      {
         "type":"PresentationDefinition",
         "credentialQuery":[
            {
               "presentationDefinition":{
                  "id":"286bc1e0-f1bd-488a-a873-8d71be3c690e",
                  "submission_requirements":[
                     {
                        "name":"Consent and Resident-card Exchange",
                        "rule":"pick",
                        "min":2,
                        "from":"A"
                     }
                  ],
                  "input_descriptors":[
                     {
                        "id":"PermanentResidentCard",
                        "name":"PermanentResidentCard",
                        "purpose":"PermanentResidentCard",
                        "group":[
                           "A"
                        ],
                        "constraints":{
                           "fields":[
                              {
                                 "path":[
                                    "$.type"
                                 ],
                                 "filter":{
                                    "type":"array",
                                    "contains":{
                                       "type":"string",
                                       "const":"PermanentResidentCard"
                                    }
                                 }
                              }
                           ]
                        }
                     }
                  ]
               }
            }
         ]
      }
   ],
   "interactServices":[
      {
         "type":"UnmediatedHttpPresentationService2021"
      }
   ],
   "isOneTime":true,
   "callback":[
      {
         "url":"FILL YOUR CALLBACK URL, for example 'https://webhook.site/efb19fb8-2579-4e1b-8614-d5a03edaaa7a'"
      }
   ]
}

Exchange Definition Structure and Properties

exchangeId

exchangeId is definition identifier, used to fetch exchange-definition

Exchange Queries

The Exchange Definition has a query property that tells which data needs to be requested. The type of queries that are supported are defined by VerifiablePresentationQueryType, for reference see VpRequestQueryType.

The DIDAuth query type is used for exchange needed for authorisation, while PresentationDefinition could be used to request certain data from the Holder.

Exchange Callbacks

When defining an exchange, callbacks can be configured to allow parties to receive notice of a VP submitted in response to an exchange. Notifications consist of POST requests to the configured URLs. A callback is configured by adding an entry to the callback array in the Exchange Definition.

Exchange Interact Services

The exchange interaction types used by this VC-API implementation are directly related to Verifiable Presentation Request Interaction Types. The interaction types indicate to the receiver of the presentation request how they can expect to interact further with the issuer/verifier.

1. Mediated Exchange Interactions

Mediated exchange interactions signal to the receiver of the presentation request that the exchange is mediated by an additional component and may not be automatically processed. Mediated exchanges therefore allow for a review of presentation submission by a human or automated process as well as the issuance of credentials based on this review.

Due to the duration of the mediation process being unknown, the submitter of the verifiable presentation may have to query repeatedly in order to check if the result of the mediation is available.

"interact": {
            "service": [
                {
                    "type": "MediatedHttpPresentationService2021",
                    "serviceEndpoint": "http://localhost:3000/exchanges/resident-card-issuance-82793/55fb5bc5-4f5f-40c8-aa8d-f3a1991637fc"
                }
            ]
        }

1. Unmediated Exchange Interactions

Mediated exchange interactions signal to the receiver of the presentation request that the exchange is not mediated by an additional component and can be automatically processed.

"interact": {
      "service": [
        {
          "type": "UnmediatedHttpPresentationService2021",
          "serviceEndpoint": "https://vc-api-dev.energyweb.org/v1/vc-api/exchanges/b6754fca-f123-43ce-8bd2-92074f05a29b/25390400-e995-4f34-8f59-5820a8ce7816"
        }
      ]
    }

serviceEndpoint

serviceEndpoint is used to continue exchanges

Presentation Definitions.

These presentation exchange take place on the basis of presentation-definition. Verifiers articulate these definitions of what they require for proofs. The issuer then wraps their Verifiable Credentials on the basis of presentation-definition in a VP and provide a response to the Verifier.

The presentation_definition are constructed of inputs, that describe the format and details for proofs required. They may also contain selection or filter rules for the presented Verifiable Credentials.

{
  "presentation_definition": {
    "id": "Scalable trust example",
    "input_descriptors": [
      {
        "id": "any type of credit card from any bank",
        "name": "any type of credit card from any bank",
        "purpose": "Please provide your credit card details",
        "constraints": {
          "fields": [
            {
              "path": [
                "$.termsOfUse.type"
              ],
              "filter": {
                "type": "string",
                "pattern": "https://train.trust-scheme.de/info"
              }
            },
            {
              "path": [
                "$.termsOfUse.trustScheme"
              ],
              "filter": {
                "type": "string",
                "pattern": "worldbankfederation.com"
              }
            },
            {
              "path": [
                "$.type"
              ],
              "filter": {
                "type": "string",
                "pattern": "creditCard"
              }
            }
          ]
        }
      }
    ]
  }
}

A presentation_definition has input_descriptors property which has an array of objects with properties describing what type of input data (credential) or sub-fields are required for submission.

See input_descriptors to know more.

Let's understand different workflows with VC-API

Presentation exchange between Holder and Issuer

issuance-exchange-flow-diagram

Presentation exchange between Holder and Verifier

presentation-exchange-flow-diagram

Example for a VC issuance and presentation using VC-API can be seen in Resident Card Tutorial.