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:
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/v1/presentations/templatesRequest
1{
2 "domain":"YOUR_TENANT_SUBDOMAIN.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": "CourseCredential",
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:
@contextis the JSON-LD schema, which should match the schema as defined in the credential that is being requested.typeis the credential type that the Mobile Wallet will use to find matching credentials that it holds.The
issuerintrustedIssuerfilters which Credentials will be acceptable. An employer, for instance, might only accept the public DIDs of certain universities.
Response
1{
2 "id": "f95e71b0-9bdf-11ea-aec9-3b5c35fc28c8",
3 "domain": "YOUR_TENANT_SUBDOMAIN.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": "CourseCredential",
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
1{
2 "domain":"YOUR_TENANT_SUBDOMAIN.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:
@contextis the JSON-LD schema, which should match the schema as defined in the credential that is being requested and must always start withhttps://www.w3.org/2018/credentials/v1and revocable credential must containhttps://w3id.org/vc-revocation-list-2020/v1.typeThe Wallet will use this to match credentials that it holds, however the current implementation requires that this is the firsttypeso will always need to be set toVerifiableCredential.the
credentialSubjectstates which claims from the credential are required for the presentation, only these claims will need to be sent to the verifier.The
issuerintrustedIssuerfilters 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
1{
2 "id": "6d597607-d64d-4209-8d2e-7e5a4587bbc8",
3 "name": "zkp-certificate-presentation",
4 "domain": "YOUR_TENANT_SUBDOMAIN.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.