Indicio Proven API Tutorial

This tutorial goes through a series of steps to exercise a few of the key features of the Proven API and help you begin to construct your own workflows.

The three major features that will be exercised are:

1. Connecting

2. Issuing a credential

3. Verifying a credential

Connecting

Call the Invitation API

To connect, one agent must issue an invitation to the other. Generally, the server agent issues an invitation to the mobile agent by displaying an invitation URL encoded in a QR code.

Request an invitation URL from the Proven API using the invitations API.

1. Use the following API endpoint: https://your.url.com/api/v1/invitations.

2. Set your x-api-key header to: 9^2m@qw2w885dKXxaup6TQ&CQT4@=RNW (or your production API key).

3. Submit the following as the POST body:

{
  "contact_id": "",
  "alias": "API Invitation",
  "invitation_type": "CV1",
  "invitation_mode": "once",
  "accept": "auto",
  "public": false,
  "invitation_role": "Holder",
  "invitation_label": "CV1",
  "invitation_status": "active",
  "invitation_description": "Invitation created through API",
  "invitation_active_starting_at": null,
  "invitation_active_ending_at": null,
  "uses_allowed": ""
}

The API will respond with something similar to the following:

{"invitation_url":"https://proven.mediator.indiciotech.io?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiNmQ0Y2QxZjYtNWJmMi00MjQ3LTg1ZmQtY2UxNzk5MjYyNDY3IiwgInJlY2lwaWVudEtleXMiOiBbIkFjOTFEWHE2ZEZzWXBZcmMyVlMzWDRrUnhHWGZtaGhaVXo1NUpSUkdSdkF5Il0sICJyb3V0aW5nS2V5cyI6IFsiRXJLRGVkNkQ1Tm9nUXpMVlBwczlrcFNXYWdxTndiVlE4RXpIcGdoTHE4UlQiLCAiMkRBQjZNU2V2bnFjc2ZoMzJIOEFrdlBIcHNzVmY3Wnl0UlZHOThTdXZXUjUiXSwgImxhYmVsIjogIlByb3ZlbiIsICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9wcm92ZW4ubWVkaWF0b3IuaW5kaWNpb3RlY2guaW8ifQ==","invitation_id":52,"contact_id":""}

Establish the Connection

Once you have an invitation, use it to establish a connection between the two agents.

Use the invitation_url from the API response and provide it to a connecting agent such as Holdr+ using Postman:

• When working with Postman, you can copy the invitation_url and use a website such as https://www.qr-code-generator.com/ to create and display a QR code that mobile agents like Holdr+ can read.

• Use Holdr+ to read the QR code by clicking on Connect in the middle of the bottom menu and pointing the camera at the QR code.

After the connecting agent reads the QR code and connects, you should see the most recent connection in Proven under Contacts.

Issuing a Credential

After establishing a connection, perform the first of two key operations by issuing a credential.

Send a credential offer to a particular contact using the credentials API.

1. Use the following API endpoint: https://your.url.com/api/v1/credentials.

2. Set your x-api-key header to: 9^2m@qw2w885dKXxaup6TQ&CQT4@=RNW (or your production API key).

3. Submit the following as the POST body (notice the invitation_id OR contact_id should match what you used in the invitations API call above):

{
"invitation_id": 52,
"contact_id": "",
"schema_id": "Gj39gdivhMneKBaamMsX7P:2:User:1.0",
"attributes": [
  {
    "name": "user_email",
    "value": "[email protected]"
  },
  {
    "name": "username",
    "value": "mike.ebert"
  },
  {
    "name": "user_id",
    "value": "1"
  },
  {
    "name": "user_roles",
    "value": "admin"
  }
]
}

The API will respond with the following message:

{
  "success": "Credential was offered"
}

The connected agent will receive a credential offer. In Holdr+, you will see a notification on the home screen. Click on it to view the offer details and to click Accept or Decline.

Accept the credential offer so that you can use it in the verification step.

Verifying a Credential

Request a Verification

After establishing a connection, the second key operation to perform is to verify a credential. In this tutorial, you will verify the credential you just issued in the previous step using the verifications API.

1. Use the following API endpoint: https://your.url.com/api/v1/verifications.

2. Set your x-api-key header to: 9^2m@qw2w885dKXxaup6TQ&CQT4@=RNW (or your production API key).

3. Submit the following as the POST body (notice the invitation_id OR contact_id should match what you used in the invitations API call above):

{
  "invitation_id": 52,
  "contact_id": "",
  "schemas": [
      {
          "schema_id": "Gj39gdivhMneKBaamMsX7P:2:User:1.0",
          "schema_attributes": [
              "user_email"
          ]
      }
  ],
  "timeout": "10",
  "rule": "no rule"
}

The API will respond with something similar to the following:

[
  {
      "verification_id": 3,
      "connection_id": "27194181-8bf5-4207-aad3-51e7ad7bbea5",
      "contact_id": null,
      "invitation_id": 52,
      "schema_id": "Gj39gdivhMneKBaamMsX7P:2:User:1.0",
      "schema_attributes": [
          "user_email"
      ],
      "timeout": 10,
      "rule": "no rule",
      "meta_data": null,
      "complete": false,
      "result": false,
      "result_string": "Pending",
      "result_data": null,
      "presentation_exchange_id": [
          "911fe7d1-1485-4997-99d8-ef858c9eab64"
      ],
      "error": "",
      "created_at": "2024-01-16T21:05:23.816Z",
      "updated_at": "2024-01-16T21:05:27.000Z"
  }
]

The connected agent will receive a presentation request. In Holdr+, you will see a notification on the home screen that you can click to view the request details and to click Accept or Decline.

Accept the request to send your credential information so that you can view it in the next step.

Request the Status of the Verification(s)

After requesting the presentation of a credential from the connected agent (and sharing it if you are the one controlling the connected agent), you can request the verification result.

If the user responds quickly or you set a long timeout, it is possible to get the presentation data back in the verification request itself. However, in most cases, you have to request the data at a later time.

1. Request the result of a verification from the verifications API using the GET method and a URL that contains the verification ID number. For example, the verification_id is 3 as seen in the response in the Request a Verification section.

2. Use the following API endpoint with the correct ID in the URL: https://your.url.com/api/v1/verifications/3.

3. Set your x-api-key header to: 9^2m@qw2w885dKXxaup6TQ&CQT4@=RNW (or your production API key).

The API will respond with something similar to the following:

{
  "verification_id": 3,
  "connection_id": "27194181-8bf5-4207-aad3-51e7ad7bbea5",
  "contact_id": null,
  "invitation_id": 52,
  "schema_id": "Gj39gdivhMneKBaamMsX7P:2:User:1.0",
  "schema_attributes": [
      "user_email"
  ],
  "timeout": 10,
  "rule": "no rule",
  "meta_data": null,
  "complete": true,
  "result": true,
  "result_string": "Verified",
  "result_data": [
      {
          "name": "user_email",
          "value": "[email protected]"
      }
  ],
  "presentation_exchange_id": [
      "911fe7d1-1485-4997-99d8-ef858c9eab64"
  ],
  "error": "",
  "created_at": "2024-01-16T21:05:23.816Z",
  "updated_at": "2024-01-16T21:05:33.964Z"
}

Note the result_data. You can now see the value of each of the attributes that you requested and use them for other credentials or in other parts of your existing or new systems.