Verifications

Introduction

Verifications allow you to request data from a digital wallet. They are a core part of SSI. A unique value proposition of verifiable credentials is that information can be verified instantly and cryptographically, without managing multiple integrations.

Verification of credentials follows a specific protocol.

  1. The verifier must first understand their risk policy. What will they accept? How will they know whether to trust the verification? These policies are known as "Verification Policies".
  2. The verifier must first request some information from the credential holder. This request is known as a "proof request" or "verification request".
  3. The holder will then decide whether/how to satisfy the request and send a response back to the verifier. They won't share the actual credentials but will simply share proof of the credentials. The response is known as a "proof presentation" or simply a "proof".
  4. Once the verifier receives the proof from the holder, they will check the digital signatures, content, and revocation status against the blockchain to ensure validity.

Feel free to reach out to our team at [email protected] if you'd like to understand more about these policies.

Create a Verification Policy

POST /verificationPolicies

A Verification Policy is created and saved on your cloud agent.

{
"name": "string", // Required. Your chosen name for this verification definition
"version": "string", // Required. The version of the verification definition. Must be in Semantic Versioning format (eg 1.1.0 or 2.3.14-alpha) - https://semver.org/
"attributes": [ // Optional. All attribute proofs in here will return the attribute values when requested.
{
"policyName": "string", // Required. This value must match the Attribute Name exactly as it is stored in the agent's wallet
"attributeNames": [
"string" // Optional. This name will show up on a wallet as the name of the proof that is defined as the value
],
"restrictions": [ // Optional. Restrictions defined in the list below will filter the proof based on the identifiers that are provided.
{// Restrictions given within the same object will be evaluated with AND operations. Restrictions given between different objects will be evalued as OR operations
"schemaId": "string", // The schema ID of the credential
"schemaIssuerDid": "string", // The issuer DID of the schema ID of the credential
"schemaName": "string", // The exact name of the schema
"schemaVersion": "string", // The exact version of the schema
"issuerDid": "string", // The issuer's public DID that can be resolved on the ledger
"credentialDefinitionId": "string", // The Credential Definition ID of the credential
"value": {
"attributeName": "string",
"attributeValue": "string"
}
},
{
... // additional requirements
}
]
},
... // additional attribute proofs can be defined here
],
"predicates": [ // Optional. All proofs defined here will return a bool if the attribute fulfills the given requirements
{
"policyName": "string", // Optional. The proof name. This will be displayed within the verification request sent to the wallet
"attributeName": "string", // Required. See above
"predicateType": "string", // Required. Predicate Type. >=, <=, or == are the only available options.
"predicateValue": 0, // Required. The value (y) to be compared with the attribute value (x) as such: x (operator) y.
"restrictions": [ // See above
{
"schemaId": "string",
"schemaIssuerDid": "string",
"schemaName": "string",
"schemaVersion": "string",
"issuerDid": "string",
"credentialDefinitionId": "string",
"value": {
"attributeName": "string",
"attributeValue": "string"
}
}
]
}
... // additional predicate proofs
],
"revocationRequirement": { // Optional. The revocation requirement should be used for proofs of credentials that support revocation
"validAt": "2020-04-15T16:35:34.026Z"
}
}

List all Verification Policies

GET /verificationPolicies

This will list all of the Verification Policies that you have created with your organization.

Get the specified Verification Policy

GET /verificationPolicies/{policyId}

Use the Verification Policy ID to get a specific Verification Policy.

List all verifications for a connection

GET /verifications

Now that you have created a Verification Policy, you can use that policy to request verification of credentials from other agents.

Use the Verification Policy ID to get a specific Verification Policy.

Create a Verification

There are currently four ways to create and send a verification request.

1. Send a verification to the specified connection from existing Verification Policy

PUT /verifications/policy/{policyId}/connections/{connectionId}

This endpoint can be used to send a Verification Policy to a connection, which will create a verification ID to track the response from the connection.

{
"policyId": "string",
"connectionId": "string"
}

2. Create a verification from existing policy used for connectionless transport

PUT /verifications/policy/{policyId}

This endpoint can be used to create a Verification Policy from an existing Verification Policy and respond with a verificationUrl that can be sent to users.

{
"policyId": "string",
}

3. Create a verification from parameters used for connectionless transport

POST /verifications/policy

This endpoint can be used to create a Verification Policy and respond with a verificationUrl that can be sent to users.

{
"name": "string",
"version": "string",
"attributes": [
{
"policyName": "string",
"attributeNames": [
"string"
],
"restrictions": [
]
}
],
"predicates": [
{
"policyName": "string",
"attributeName": "string",
"predicateType": "string",
"predicateValue":"string",
"restrictions": [
]
}
]
}

4. Send a verification to the specified connection from parameters

PUT /verifications/policy/connections/{connectionId}

This endpoint can be used to create a Verification Policy and respond with a verificationUrl that can be sent to users.

{
"name": "string",
"version": "string",
"attributes": [
{
"policyName": "string",
"attributeNames": [
"string"
],
"restrictions": [
]
}
],
"predicates": [
{
"policyName": "string",
"attributeName": "string",
"predicateType": "string",
"predicateValue":"string",
"restrictions": [
]
}
]
}

Create a Connectionless Verification

PUT /verifications/policy/{policyId}

This endpoint can be used to create a verification from existing policy used for connectionless transport.

{
"policyId": "string",
}

Get verification by identifier

GET /verifications/{verificationId}

This endpoint should be used to get each verification by its identifier.

See above for description of attributes.

Execute Verification for Ledger

GET /verifications/{verificationId}/verify

Verify the proof against the ledger.

Additional Information

Explanation of Restrictions List

In the verification template, the restrictions list defines where this data is allowed to come from. The three most useful options include:

  • schemaId: Anyone who creates a credential with a certain schema ID can issue it to an individual. The schema ID only provides trust that the data is in the correct format.

  • credentialDefinitionId: Because a Credential Definition is signed by an issuer, the Credential Definition defines both the format of the data and also who sent it to the wallet. This is the most commonly used restriction when contructing definitions. The Credential Definition would be an ID that is written to the Sovrin Ledger, and will prove that the credential an agent sends to you is both issued by the organization and is in the format that you need.

  • issuerDid: For situations where you only care about where the credential is from and not what format the data is in, you may also use only the issuer's DID. This is also resolvable on the Sovrin Network and will prove that the data you have received was sent from a trusted source. It will not provide any information around the format of the data that you're receiving.

When sending a Verification, you may choose to request an Attribute Policy or a Predicate Policy. The attribute proofs will reveal the actual data of each attribute you request. The Predicate proofs will only return a True or False value on whether the attribute matches your specified query. For example, if someone's Date of Birth is before 1998, you may request that the person provide their Year of Birth attribute, and only from the Driver's License or Passport credentials issued by the US Government:

{
...
"proof_of_year_of_birth": {
"p_type": "<=",
"p_value": "1998",
"name": "Year of Birth",
"restrictions": [
{
"cred_def_id": "<US_drivers_license_cred_def_id>"
},
{
"cred_def_id": "<drivers_license_cred_def_id>"
}
]
}
...
}

This will return either a true or false value to the attribute that a user supplies. If the value's signature matches the signatures stored in the Credential Definition, it will return true. This value can be trusted to have come from whichever Credential Definition ID has been specified, which can only be created by a unique issuer on the sovrin network.

Predicate Proofs

Predicate proofs have four possible types: >=, >, <=, and <. The name must match the attribute name exactly, both in spelling and in capitalization in order to be recognized.