User Guide - SSI-Solutions/vcms GitHub Wiki

This page describes a common issuing and verification flow, describing the required REST calls to the client. You should review the accompanying demo scripts setup Demo setup, especially the example scripts for issuing and verification.

For further details and examples on the API usage, refer to the Swagger UI of the deployed environment of the Issuer, Verifier, and Connector instances respectively. This is available on the /swagger-ui/index.html path of the services.

Issuing a new credential

  1. Get a list of available credential definitions
GET https://issuer.backend/issue/credentials/definitions

The resulting JSON object lists the available credential definitions, and the name of the claims in each of the credDefs. Decide which credDef you will want to issue, and take note of the credentialDefinitionId.

  1. Create a new connection and invitation process
POST https://connector.backend/connection/invitation

The resulting connectionId will be used later on to track this connection in VCMS. Use the invitationUrl is necessary for the mobile wallet app to receive the invitation. This is normally done by representing this URL as a QR code, and scanning it from a mobile wallet application.

  1. Poll for the connection status
GET https://connector.backend/connection/`connectionId`

Wait for the result to be "responded" or "established", meaning the mobile wallet accepted the connection.

  1. Create a new issuing process for the existing connection
POST https://issuer.backend/issue/process

The JSON message towards the issuer specify the connectionId received above, the chosen credentialDefinitionId, and the attributes as JSON object describing the attribute names and clear text values for the credential. The 'userID' is an optional field, and can be omitted.

Note the resulting processId, representing the issuing process in VCMS.

  1. Poll for the issuing state
GET https://issuer.backend/issue/process/`processId`/state

The state should be "VC_ISSUED", meaning the mobile wallet successfully accepted and received the credential. The issuing process is completed.

Verify and present a credential

  1. Get a list of available credential definitions
GET https://verifier.backend/issue/credentials/definitions

If unsure, review the available credential definitions on the verifier server. You do not need to do this if you already know the credentialDefinitionId.

  1. Create a new connection and invitation process
POST https://connector.backend/connection/invitation

The resulting connectionId will be used later on to track this connection in VCMS. Use the invitationUrl is necessary for the mobile wallet app to receive the invitation. This is normally done by representing this URL as a QR code, and scanning it from a mobile wallet application.

  1. Poll for the connection status
GET https://connector.backend/connection/`connectionId`

Wait for the result to be "responded" or "established", meaning the mobile wallet accepted the connection.

  1. Request a verification on the existing connection
POST https://verifier.backend/verify/process

The JSON message towards the issuer specify the connectionId received above, the chosen credentialDefinitionId, and the attributes as a list of names field names requested to be revealed. Typically all attributes available on the credDef are included.

Note the resulting processId, representing the verification process in VCMS.

  1. Poll for the verification state
GET https://verifier.backend/verify/process/`processId`/state

The state should be "VERIFIED", meaning the mobile wallet accepted the request, and presented a valid credential.

  1. Request the presented claims on the successful verification
GET https://verifier.backend/verify/process/`processId`/claims

The resulting JSON object collects the key-value pairs for the revealed attributes names and values. The verification process is completed.