Learn

Create a Presentation Template

Introduction

In order to obtain information from a Verifiable Credential that’s being held in a Mobile Wallet, the verifier must request these claims from the Credential holder using a Presentation Request, the holder in turn may provide the Credential in the form of a Verifiable Presentation. The short-lived presentation request itself is derived from a Presentation Template, which defines what type of Credential the verifier is requesting.

Pre-Requisites

You need access to the MATTR Platform APIs. If you’re experiencing difficulty, contact us

In order to request a certain credential, you need to know the following properties of that credential:

  • the Type of the credential

  • the JSON-LD schema of the credential

  • the public DIDs of Issuers whose credentials you are willing to accept

  • Additionally for ZKP-enabled credentials, you will also need to specify the exact claims you are requesting from the Holder and know that the issuer’s DID is using a BLS key type.

Presentation Template for Credentials

Note: the same technique is used to perform DID authentication on the platform, follow the Authenticate a DID tutorial to learn more.

A Presentation Template defines which credentials are required for presentation. This template is long-lived in the platform and is used to create the actual Presentation Request (with a default expiry 5 mins), which is used by the Mobile Wallet to select which credential(s) it should display to the Holder, before asking for confirmation to use them to create the Presentation sent in response to the request.

Create a Basic Presentation Template

The basic form of a Presentation Template uses the Verifiable Presentation Request Specification Query by Example format. This query uses the credential type and trustedIssuer to specifically only accept Presentations from matching credentials.

On presentation all the claims from Credentials matching the query are sent in the Presentation, along with the SubjectDIDs used for each Credential.

Create a Presentation Template by providing a payload:

http
Copy to clipboard. 
1POST https://tenant.vii.mattr.global/v1/presentations/templates

Request

json
Copy to clipboard. 
1{
2    "domain":"tenant.vii.mattr.global",
3    "name":"certificate-presentation",
4    "query":[{
5        "type": "QueryByExample",
6        "credentialQuery": [{
7            "required": true,
8            "reason": "Please provide your certificate.",
9            "example": {
10                "@context": ["https://schema.org"],
11                "type": "Course",
12                "trustedIssuer": [{
13                    "required": true,
14                    "issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"
15                }]
16            }
17        }]
18    }]
19}

The domain indicates to the Mobile Wallet user the domain of the verifier (currently this must always match your tenant). A further check is completed on the domain linkage credential found at the Well Known DID Configuration endpoint. The validity of this is displayed to the holder before they respond to the presentation request.

The reason is shown in the Mobile Wallet to give context around why a credential is being requested.

As part of the example query:

  • @context is the JSON-LD schema, which should match the schema as defined in the credential that is being requested.

  • type is the credential type that the Mobile Wallet will use to find matching credentials that it holds.

  • The issuer in trustedIssuer filters which Credentials will be acceptable. An employer, for instance, might only accept the public DIDs of certain universities.

Response

json
Copy to clipboard. 
1{
2    "id": "f95e71b0-9bdf-11ea-aec9-3b5c35fc28c8",
3    "domain": "tenant.vii.mattr.global",
4    "query": [
5        {
6            "type": "QueryByExample",
7            "credentialQuery": [
8                {
9                    "required": true,
10                    "reason": "Please provide your certificate.",
11                    "example": {
12                        "@context": [
13                            "https://schema.org"
14                        ],
15                        "type": "Course",
16                        "trustedIssuer": [
17                            {
18                                "required": true,
19                                "issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"
20                            }
21                        ]
22                    }
23                }
24            ]
25        }
26    ],
27    "name": "certificate-presentation"
28}

Create a Privacy-Preserving Presentation Request Template (for ZKP-enabled credentials)

As a Verifier it is generally in your interest to only request essential information from credential holders, ZKP-enabled credentials allow the mobile wallet to derive presentations of only the verifiable credential claims that are required. This derived presentation is still verifiable as being issued by the trusted issuer and cannot be tampered with.

To facilitate this matching of Credentials and claim information a query type of queryByFrame that uses JSON-LD Framing to establish the JSON-LD tree layout as well as still specifying a credential type and trustedIssuer DID.

NOTE: This is an experimental feature in MATTR VII.
The use of JSON-LD Framing is also a novel technique to request verifiable presentations, not all features from JSON-LD framing are supported and configurations must be thoroughly tested to ensure there are no unforeseen results.
You can read more about our work on privacy-preserving verifiable credentials on our blog.

Request

json
Copy to clipboard. 
1{
2    "domain":"tenant.vii.mattr.global",
3    "name":"zkp-certificate-presentation",
4    "query": [{
5         "type":"QueryByFrame",
6         "credentialQuery":[
7            {
8               "reason": "Please provide your educational award and surname from your Certificate",
9               "frame":{
10                  "@context":[
11                    "https://www.w3.org/2018/credentials/v1",
12                     "https://w3id.org/vc-revocation-list-2020/v1",
13                     "https://schema.org"
14                  ],
15                  "type": "VerifiableCredential",
16                  "credentialSubject":{
17                     "@explicit":true,
18                     "educationalCredentialAwarded":{ },
19                     "familyName":{ }
20                  }
21               },
22               "trustedIssuer":[
23                  {
24                     "issuer":"did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
25                     "required":true
26                  }
27               ],
28               "required":true
29            }
30         ]
31      }]
32}

The domain indicates to the Mobile Wallet user the domain of the verifier (currently this must always match your tenant). A further check is completed on the domain linkage credential found at the Well Known DID Configuration endpoint. The validity of this is displayed to the holder before they respond to the presentation request.

The reason is shown in the Mobile Wallet to give context around why a credential is being requested.

As part of the frame query:

  • @context is the JSON-LD schema, which should match the schema as defined in the credential that is being requested and must always start with https://www.w3.org/2018/credentials/v1 and revocable credential must contain https://w3id.org/vc-revocation-list-2020/v1.

  • type The Wallet will use this to match credentials that it holds, however the current implementation requires that this is the first type so will always need to be set to VerifiableCredential.

  • the credentialSubject states which claims from the credential are required for the presentation, only these claims will need to be sent to the verifier.

  • The issuer in trustedIssuer filters which Credentials will be acceptable. An employer, for instance, might only accept the public DIDs of certain universities. For ZKP-enabled credentials you need to ensure this DID is using a BLS key type.

Response

json
Copy to clipboard. 
1{
2  "id": "6d597607-d64d-4209-8d2e-7e5a4587bbc8",
3  "name": "zkp-certificate-presentation",
4  "domain": "tenant.vii.mattr.global",
5  "query": [
6    {
7      "type": "QueryByFrame",
8      "credentialQuery": [
9        {
10          "reason": "Please provide your educational award and surname from your Certificate",
11          "frame": {
12            "@context": [
13              "https://www.w3.org/2018/credentials/v1",
14               "https://w3id.org/vc-revocation-list-2020/v1",
15              "https://schema.org"
16            ],
17            "type": "VerifiableCredential",
18            "credentialSubject": {
19              "@explicit": true,
20              "educationalCredentialAwarded": {},
21              "familyName": {}
22            }
23          },
24          "trustedIssuer": [
25            {
26              "issuer": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
27              "required": true
28            }
29          ],
30          "required": true
31        }
32      ]
33    }
34  ]
35}

Next Steps

Once you have the Presentation Request Template configured, the template ID can be used in setting up your tenant to verify a credential using a Callback or using OIDC Bridge, alternatively, try Verifying a ZKP-enabled Credential.

Further Configuration Options

Both forms of Presentation Templates accept an array of queries inside a single request, it is recommended that you experiment with this behavior to ensure you get the desired outcomes.