Create a basic presentation template

Basic presentation templates define what type of credential is required for a particular verification workflow. They are used to create presentation requests that are shared with a specific holder.

The basic presentation template uses the Verifiable Presentation Request Specification QuerybyExample query method, a W3C standard. This query method uses the credential type and trustedIssuer to only accept verifiable presentations that match these parameters. All the claims from credentials matching the query are sent in the presentation, along with the Subject DIDs used for each credential.

Refer to Create a selective-disclosure presentation template for additional supported query methods.

Prerequisites

  • Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

  • Requested credential properties:

    • The credential type.

    • What claims are included in the credential (i.e. its JSON-LD schema).

    • The Issuers DIDs whos credentials you are willing to accept.

Request

Make a request of the following structure to create a basic presentation template:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/presentations/templates
json
Copy to clipboard.
1{
2    "domain": "YOUR_TENANT_URL",
3    "name": "certificate-presentation",
4    "query": [
5        {
6            "type": "QueryByExample",
7            "credentialQuery": [
8                {
9                    "required": true,
10                    "reason": "Please provide your certificate.",
11                    "example": {
12                        "@context": [
13                            "https://exampleschema.com"
14                        ],
15                        "type": "CourseCredential",
16                        "trustedIssuer": [
17                            {
18                                "required": true,
19                                "issuer": "did:web:organization.com"
20                            }
21                        ]
22                    }
23                }
24            ]
25        }
26    ]
27}
  • domain: Informs the wallet holder what domain is the verification request coming from. The value must match your tenant URL or your custom domain (if you have one set up). If the domain validation is not successful, the wallet will not let the user proceed with the verification workflow.

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.

  • name: Unique value that is used internally to manage your templates. It must be unique across all presentation templates on your tenant, but is not shown to the holder.

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

    • type: Indicates what type of query method would be used by presentation requests created from this presentation template. For basic presentation templates you must use QueryByExample. Refer to Create a selective-disclosure presentation template for additional supported query methods.

    • credentialQuery:

      • required: When set to true, the verification workflow will fail if a matching credential is not provided in the verifiable presentation response. You can only change this to false when your templates has multiple credentialQuery objects.

      • reason: This value is displayed in the mobile wallet to provide the holder with context around why a credential is being requested. Ensure that this is written exactly as you would like it to appear to the user.

      • example:

        • @context: This is the JSON-LD schema that will be used to expand the example in the query. This example query would match any credential that has the same expanded "http://exampleschema.com/CourseCredential" type, and only matched credentials will be included in the presentation response.

          In case the credential uses a specific JSON-LD schema, you must add that schema into the @context array so that the credential could be matched against the presentation request.

        • type: The credential type that the mobile wallet will use to return matching credentials. In this example, the verifier is seeking to obtain credential of type CourseCredential. Upon the holder's consent, the wallet would only return credentials that match this type and have been issued by the issuers included in the trustedIssuer object. Credentials type is set when you issue a credential. When you include multiple credential types, the wallet will only return credentials that include all of the included types.

        • trustedIssuer: This array is used to determine what credential issuers to accept in this verification workflow. For example, an employer might only accept credentials issued by certain universities. Each object includes a issuer field which holds the issuer's DID, and a required field which indicates whether this issuer is required for a credential to be accepted in this workflow. In this example only one issuer is trusted but you can add multiple trusted issuers. Alternatively, if you want to accept credentials from any issuer as long as they match the defined credential type, leave this array empty.

All the attributes are case-sensitive. Be sure to check capitalisation and thoroughly test your configuration before running them in production.

Response

json
Copy to clipboard.
1{
2    "id": "f95e71b0-9bdf-11ea-aec9-3b5c35fc28c8",
3//... rest of Basic presentation
4}
  • id: Unique identifier for this presentation template on your tenant. You will need it to create a presentation request based on this template. You can also use it to retrieve, update (for example to include from trusted issuers or to update a custom domain) or remove this presentation template.

What's next?

Once you created a presentation template, you can use it to verify a credential using a callback or using OIDC Bridge.