Learn

Create a basic presentation template

Prerequisites

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 (ie. what claims are in the credential)

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

The basic form of a presentation template uses the Verifiable Presentation Request Specification Query by Example format, a standard from the W3C. This query uses the credential type and trustedIssuer to specifically only accept Presentations from these matching parameters.

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://YOUR_TENANT_URL/v2/credentials/web-semantic/presentations/templates

Request

For example, a verifier seeking to obtain credentials of type "CourseCredential" would create the request below. The wallet would display credentials that match this type and additionally only show ones that have been issued by the DIDs listed in the trusted issuer block. In this case, only one issuer is trusted but you can add multiple trusted DIDs.

json
Copy to clipboard. 
1{
2    "domain":"YOUR_TENANT_URL",
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:web:organization.com"
15                }]
16            }
17        }]
18    }]
19}

The domain indicates to the mobile wallet user the domain of the verifier that the request is coming from. This must always match your tenant URL or custom domain if you have set one up. You can learn more about setting up a custom domain here.

If you set up a custom domain later, any previous templates created where the domain is your tenant URL will become invalid. You will need to change any prior templates to use the custom domain.

If the domain validation is not successful, the wallet will not let the user proceed with sending you a credential.

The name is a unique value that is intended to be used internally to let you manage your templates. It will not be shown to the wallet user.

The reason is shown in the mobile wallet to give context around why a credential is being requested. Ensure that this is written exactly as you would like it to appear to the user.

You can request multiple credentials in one request by adding objects to the query array. In the case above, the query array only contains a single query and is therefore asking for one credential.

As part of the example query:

  • @context is the JSON-LD schema, which is used to expand the example in the query. Match is performed on the expanded type of the credential.

For example, in this example query, the expanded type

"http://schema.org/CourseCredential" would match any credential that has the same

expanded type.

  • 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. You can add multiple trusted issuers inside the trustedIssuer array.

Response

json
Copy to clipboard. 
1{
2    "id": "f95e71b0-9bdf-11ea-aec9-3b5c35fc28c8",
3    "domain": "YOUR_TENANT_URL",
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:web:organization.com"
20                            }
21                        ]
22                    }
23                }
24            ]
25        }
26    ],
27    "name": "certificate-presentation"
28}

Take a note of the id generated for your template. You will use this to create presentation requests.

Further configuration options

Both basic and selective-disclosure forms of Presentation Templates accept an array of queries inside a single request, it is recommended that you experiment with adding multiple credential requests into a single template to ensure you get the desired outcomes.

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.