Presentations

The presentation is signed using the holder's private key as it is being created. To validate the presentation, the verifier must also check the issuer's signature and the holder's public key. One way to achieve this is to make the holder have a DID too, so that the verifier can look up the DID on the chain and learn the public key.

The API allows you to create and sign a verifiable presentation out of one or more Verifiable Credentials.

For a detailed example of the presentations workflow. Please refer here.

Create Presentation

The holder while creating the presentation signs it with his private key. For the verifier to verify the presentation, in addition to verifying the issuer's signature, he/she needs to verify this signature as well, and for that he must know the holder's public key.

This is an operation to create and sign a verifiable presentation out of one or more Verifiable Credentials.

Parameters

NameInTypeRequiredDescription

holder

body

true

DID as fully qualified, e.g., did:dock:xyz.

challenge

body

string

false

Presentation's Challenge in a string format. The default value for this is random hex string. NOTE: if this presentation is being created to respond to a proof-request the challenge should be set to the value from the nonce field in the proof-request.

domain

body

string

false

A domain for the proof in a string format. The default value for the domain is dock.io.

credentials

body

false

Verifiable (signed) Credential returned by API.

Enumerated Values

ParameterValueDescription

type

Sr25519Signature2020 or Ed25519Signature2018 or EcdsaSecp256k1Signature2019

Type of Signature.

proofPurpose

assertionMethod or authentication

The purpose the credential will be used for.

Responses

StatusMeaningDescriptionSchema

200

The request was successful and returns a Verifiable Presentation.

400

The request was unsuccessful, because of invalid/insufficient parameters.

401

The request was unsuccessful, either because of a missing/invalid auth header or you don't own the DID.

402

Transaction limit reached or upgrade required to proceed

POST /presentations REQUEST PAYLOAD

{
  "holder": "did:dock:xyz",
  "challenge": "string",
  "domain": "string",
  "credentials": [
    {
      "@context": [
        "string"
      ],
      "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
      "type": [
        "string"
      ],
      "credentialSubject": {},
      "issuer": "did:dock:xyz",
      "issuanceDate": "2019-08-24T14:15:22Z",
      "expirationDate": "2019-08-24T14:15:22Z",
      "credentialStatus": {},
      "proof": {
        "type": "Sr25519Signature2020",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "string",
        "created": "2019-08-24T14:15:22Z",
        "proofValue": "string"
      }
    }
  ]
}
POST /presentations REQUEST CURL
curl --location --request POST https://api.dock.io/presentations/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "holder": "did:dock:xyz",
  "challenge": "string",
  "domain": "string",
  "credentials": [
    {
      "@context": [
        "string"
      ],
      "id": "https://creds.dock.io/f087cbfabc90f8b996971ba47598e82b1a03523cb9460217ad58a819cd9c09eb",
      "type": [
        "string"
      ],
      "credentialSubject": {},
      "issuer": "did:dock:xyz",
      "issuanceDate": "2019-08-24T14:15:22Z",
      "expirationDate": "2019-08-24T14:15:22Z",
      "credentialStatus": {},
      "proof": {
        "type": "Sr25519Signature2020",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "string",
        "created": "2019-08-24T14:15:22Z",
        "proofValue": "string"
      }
    }
  ]
}'
200 Response
{

  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type": ["VerifiablePresentation", "CredentialManagerPresentation"],
  "verifiableCredential": [{  }],
  "proof": [{  }]
}

Create Proof Request

It often makes sense for a verifier to request proof of credentials from a holder. For this, we have built a proof requests system into the API that works with the Dock Wallet. When a request is created, you will receive a URL which you should display in a QR code for a wallet application to scan. You can define which attributes should exist in the credential, a name for the holder and yourself to see and a nonce/challenge which prevents replay attacks.

Our system supports the DIF Presentation Exchange (PEX) syntax for querying and filtering credentials.

See the https://identity.foundation/presentation-exchange/#input-descriptor-extensions for more examples, but a few common use cases are:

Require a numeric attribute to be within a range

For example, a verifier might require that the holder have an income between $100,000 and $200,000 per year. This could be requested using the following input_descriptor

{
  path: ['$.credentialSubject.income.2022.total'],
  filter: {
    type: 'number',
    minimum: 100000,
    maximum: 200000
  },
}

Require a date attribute to be within a range

For example, a verifier might require that the credential be issued after a certain date. In this example the verifier is requiring that the credential was issued between January 1, 2020 and December 31, 2020.

{
  path: ['$.issuanceDate'],
  filter: {
    "type": "string",
    "format": "date",
    "formatMinimum": "2020-01-01",
    "formatMaximum": "2020-12-31"
  },
}

Parameters

NameInTypeRequiredDescription

attributes

body

object

false

Requested attribute specifications of proof request

name

body

string

false

Proof request name, will be shown to the holder

nonce

body

string

false

Nonce or challenge for the presentation to match

Responses

StatusMeaningDescriptionSchema

200

The request was successful and returns a Verifiable Presentation.

400

The request was unsuccessful, because of invalid/insufficient parameters.

401

The request was unsuccessful, either because of a missing/invalid auth header or you don't own the DID.

402

Transaction limit reached or upgrade required to proceed

POST /proof-requests REQUEST PAYLOAD
{
	"name": "Proof Request Test",
	"purpose": "Prove income",
	"request": {
		"input_descriptors": [
			{
				"id": "ProofIncome-1",
				"name": "Proof Request Test",
				"purpose": "Prove income",
				"constraints": {
					"fields": [
						{
							"path": [
								"$.credentialSubject.id",
								"$.credentialSubject.income.total"
							]
						}
					]
				}
		  ]
    }
	}
POST /proof-requests REQUEST CURL
curl --location --request POST https://api.dock.io/proof-requests/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
	"name": "Proof Request Test",
	"purpose": "Prove income",
	"request": {
		"input_descriptors": [
			{
				"id": "ProofIncome-1",
				"name": "Proof Request Test",
				"purpose": "Prove income",
				"constraints": {
					"fields": [
						{
							"path": [
								"$.credentialSubject.id",
								"$.credentialSubject.income.total"
							]
						}
					]
				}
		  ]
    }
	}'
200 Response
{
  "id": "aeec1776-84c3-4783-b80b-c6690a652892",
  "name": "Proof Request Test",
  "nonce": "1234567890",
  "verified": false,
  "created": "2022-10-17T22:48:30.619Z",
  "updated": "2022-10-17T22:48:30.619Z",
  "presentation": {},
  "response_url": "https://api.dock.io/proof-requests/aeec1776-84c3-4783-b80b-c6690a652892/send-presentation",
  "type": "proof-request",
	"qr": "https://creds-testnet.dock.io/proof/acaae15e-3c6e-412e-951e-4dc129b9745a",
  "request": {
		"input_descriptors": [
			{
				"id": "ProofIncome-1",
				"constraints": {
					"fields": [
						{
							"path": [
								"$.credentialSubject.income.total"
							],
              "filter": {
                "type": "number",
                "minimum": 100000,
                "maximum": 200000
              }
						}
					]
				}
			}
		]
	}
}

List Proof Requests

Return a list of all proof requests and their verification status

Parameters

NameInTypeRequiredDescription

offset

query

integer

false

How many items to offset by for pagination

limit

query

integer

false

How many items to return at one time (max 64)

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will return all proof requests created by the user.

Inline

GET /proof-requests REQUEST CURL
curl --location --request GET https://api.dock.io/proof-requests/ \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw'{

  }'
200 Response
[
  {
		"id": "f2ea3225-ef6b-44d7-a37c-7713c66875b5",
		"name": "Proof of Bachelors of Education",
		"nonce": "6684fb3d878f2c3a25e35e36045bde8d",
		"verified": false,
		"created": "2023-04-05T22:00:25.729Z",
		"updated": "2023-04-05T22:00:25.729Z",
		"presentation": {},
		"response_url": "https://api-testnet.dock.io/proof-requests/f2ea3225-ef6b-44d7-a37c-7713c66875b5/send-presentation",
		"type": "proof-request",
		"qr": "https://creds-testnet.dock.io/proof/f2ea3225-ef6b-44d7-a37c-7713c66875b5",
		"request": {
			"input_descriptors": [
				{
					"id": "Credential 1",
					"name": "Proof of Bachelors of Education",
					"purpose": "Prove that the holder has a Bachelors of Education degree",
					"constraints": {
						"fields": [
							{
								"path": [
									"$.credentialSubject.degreeName",
									"$.credentialSubject.degreeType",
									"$.credentialSubject.dateEarned | date: \"%B %d, %Y\"",
									"$.credentialSubject.fullName"
								]
							},
							{
								"path": [
									"$.name"
								],
								"filter": {
									"type": "string",
									"pattern": "Bachelors of Education"
								}
							}
						]
					}
				}
			]
		}
	}
]

Get Proof Request

Get the details of an existing proof request and its verification status.

Parameters

NameInTypeRequiredDescription

id

path

UUID

true

Proof request UUID

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will return the proof request.

404

The request was unsuccessful, because the proof request was not found.

GET /proof-requests/{id} REQUEST CULR
curl --location --request GET https://api.dock.io/proof-requests/{id} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''
200 Response
{
	"qr": "https://creds-testnet.dock.io/proof/acaae15e-3c6e-412e-951e-4dc129b9745a",
	"id": "fcaae15e-3c6e-412e-951e-4dc129b9745a",
	"name": "Proof Request Test",
	"nonce": "ffa6d005dfd8ddecf1664079bda1af1e",
	"created": "2023-05-16T15:42:53.925Z",
	"updated": "2023-05-16T15:42:53.925Z",
	"verified": false,
	"response_url": "https://api-testnet.dock.io/proof-requests/acaae15e-3c6e-412e-951e-4dc129b9745a/send-presentation",
	"request": {
		"id": "acaae15e-3c6e-412e-951e-4dc129b9745a",
		"input_descriptors": [
			{
				"id": "ProofIncome-1",
				"constraints": {
					"fields": [
						{
							"path": [
								"$.credentialSubject.id",
								"$.credentialSubject.income.total"
							]
						}
					]
				}
			}
		]
	},
	"type": "proof-request"
}

List Proof Request Templates

When working with Proof Requests you will often want to request the same information from holders. To make this easier you can create Proof Request Templates to define the contents of the proof requests to be re-used.

Parameters

NameInTypeRequiredDescription

offset

query

integer(int32)

false

How many items to offset by for pagination

limit

query

integer(int32)

false

How many items to return at one time (max 64)

Responses

StatusMeaningDescriptionSchema

200

A paged array of proof templates

GET /proof-templates REQUEST CURL
# You can also use wget
curl -X GET https://api-testnet.dock.io/proof-templates \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'
200 Response
[
  {
		"id": "dcd6e820-5ea6-4835-8ad5-ddf3de82f3d2",
		"name": "Test Proof Template",
		"created": "2023-05-09T13:18:09.290Z",
		"updated": "2023-05-09T13:18:09.290Z",
		"request": {
			"input_descriptors": [
				{
					"id": "Credential 1",
					"name": "Test Proof Template",
					"purpose": "University Degree with name, issued date requested",
					"constraints": {
						"fields": [
							{
								"path": [
									"$.credentialSubject.name",
									"$.issuanceDate"
								]
							},
							{
								"path": [
									"$.type[*]"
								],
								"filter": {
									"type": "string",
									"pattern": "UniversityDegree"
								}
							}
						]
					}
				}
			]
		}
	}
]

Create Proof Request Template

Parameters

NameInTypeRequiredDescription

body

body

true

Proof template object

Responses

StatusMeaningDescriptionSchema

200

Proof request template created

400

Invalid parameters

402

Transaction limit reached or upgrade required to proceed

POST /proof-templates REQUEST CURL
# You can also use wget
curl -X POST https://api-testnet.dock.io/proof-templates \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'
Body parameter
{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string"
}
200 Response
{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Get Proof Template History

Get all of the previously created proof requests based on the specified template.

Parameters

NameInTypeRequiredDescription

id

path

string(uuid)

true

Proof template UUID

offset

query

integer(int32)

false

How many items to offset by for pagination

limit

query

integer(int32)

false

How many items to return at one time (max 64)

Responses

StatusMeaningDescriptionSchema

200

Returns the information about the proof request history

404

Proof template was not found.

GET /proof-templates/{id}/history REQUEST CURL
# You can also use wget
curl -X GET https://api-testnet.dock.io/proof-templates/{id}/history \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'
200 Response
[
  {
    "attributes": {
      "property1": {
        "name": "favouriteDrink",
        "names": [
          "age"
        ]
      },
      "property2": {
        "name": "favouriteDrink",
        "names": [
          "age"
        ]
      }
    },
    "name": "Proof request",
    "nonce": "1234567890",
    "qr": "string"
  }
]

Create Proof Request from a Template

Create a proof requtest based on the specified template.

Parameters

NameInTypeRequiredDescription

body

body

object

true

Specify optional nonce and domain

ยป nonce

body

string

false

none

ยป domain

body

string

false

none

id

path

string(uuid)

true

Proof template UUID

Responses

StatusMeaningDescriptionSchema

200

Returns the information about the proof request

402

Transaction limit reached or upgrade required to proceed

404

Proof template was not found.

POST /proof-templates/{id}/request REQUEST CURL
# You can also use wget
curl -X POST https://api-testnet.dock.io/proof-templates/{id}/request \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'
Body parameter
{
  "nonce": "string",
  "domain": "string"
}
200 Response
{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "response_url": "string",
  "verified": true,
  "presentation": {},
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Get Proof Template

Get the details about a specific template.

To perform this operation, you must be authenticated by means of one of the following methods: accessToken, bearerAuth, rapidAPI

Parameters

NameInTypeRequiredDescription

id

path

string(uuid)

true

Proof template UUID

Responses

StatusMeaningDescriptionSchema

200

Returns the information about the proof templates

404

Proof templates was not found.

GET /proof-templates/{id} REQUEST CURL
# You can also use wget
curl -X GET https://api-testnet.dock.io/proof-templates/{id} \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'
200 Response
{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Update Proof Template

Parameters

NameInTypeRequiredDescription

body

body

true

Proof template object

id

path

string(uuid)

true

Proof template UUID

Responses

StatusMeaningDescriptionSchema

200

Profile has been updated

400

Error creating profile

402

Transaction limit reached or upgrade required to proceed

404

Proof templates was not found.

PATCH /proof-templates/{id} REQUEST CURL
# You can also use wget
curl -X PATCH https://api-testnet.dock.io/proof-templates/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'
Body parameter
{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string"
}
200 Response
{
  "attributes": {
    "property1": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    },
    "property2": {
      "name": "favouriteDrink",
      "names": [
        "age"
      ]
    }
  },
  "name": "Proof request",
  "nonce": "1234567890",
  "qr": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error": "string",
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Delete Proof Template

Deletes the specified template and any associated data.

Parameters

NameInTypeRequiredDescription

id

path

string(uuid)

true

Proof template UUID

Responses

StatusMeaningDescriptionSchema

200

Proof templates will be deleted

None

400

Something went wrong.

404

Proof templates was not found.

DELETE /proof-templates/{id} REQUEST CURL
# You can also use wget
curl -X DELETE https://api-testnet.dock.io/proof-templates/{id} \
  -H 'Accept: application/json' \
  -H 'DOCK-API-TOKEN: API_KEY'
400 Response
{
  "status": 0,
  "type": "string",
  "message": "string"
}

Last updated