Learn

Create a presentation request

Once your local environment is setup, the next step is to create a presentation request. This request is based on an existing presentation template and defines the types of credentials and claims required for this verification workflow.

Prerequisites

Request

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

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/presentations/requests
json
Copy to clipboard.
1{
2  "challenge": "GW8FGpP6jhFrl37yQZIM6w",
3  "did": "did:web:example.com",
4  "templateId": "f95e71b0-9bdf-11ea-aec9-3b5c35fc28c8",
5  "callbackUrl": "http://71df02cc96e5.ngrok.io/callback/g87Grad",
6  "expiresTime": 1638836401000
7}

  • challenge: This unique identifier will be used to validate the presentation response sent to the configured callbackUrl. By comparing challenge with the challengeId value in the response, you can ensure it was sent by the intended MATTR VII tenant.

  • did: This is the DID associated with the verifier. It must be available on the tenant and have a key type that is able to be used for messaging (e.g. a ed25519 key type).

  • templateId: Use the id value of an existing presentation template that will be used to create the presentation request.

  • callbackUrl: This is the path that you want MATTR VII to message (in the form of a JSON body) once it has received and processed the verifiable presentation from the mobile wallet holder:

    • Must be a valid URL.

    • Must use the HTTPS protocol.

    • Must not be an IP address.

    • Must not include query parameters.

    • Must be available, accept POST requests and respond with a 200 OK.

    • The callback URL will not be present directly in the signed presentation request. We highly recommend protecting the callback endpoint by including a unique identifier in the URL to create a unique callback URL for each request, which would make it hard to guess.

    • We recommend the callback endpoint always responds with a 404 header to any unsuccessful calls.

  • expiresTime: Once the time (Unix time) is reached the presentation corresponding to the challenge will not be accepted. For the purpose of testing you may wish to extend this out. Defaults to five minutes if no value is provided.

Response

json
Copy to clipboard.
1{
2    "id": "38d9ca70-8b61-48c3-9efc-b67d97410743",
3    "callbackUrl": "http://71df02cc96e5.ngrok.io/callback/g87Grad",
4    "request": {
5        "id": "38d9ca70-8b61-48c3-9efc-b67d97410743",
6        "type": "https://mattr.global/schemas/verifiable-presentation/request/QueryByExample",
7        "from": "did:web:example.com",
8        "created_time": 1607300517863,
9        "expires_time": 1638836401000,
10        "reply_url": "https://YOUR_TENANT_URL/core/v2/credentials/web-semantic/presentations/response",
11        "reply_to": [
12            "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"
13        ],
14        "body": {
15            "id": "5770506c-9ce9-4d54-b295-68ad2bb12a4c",
16            "name": "certificate-presentation",
17            "domain": "tenant.vii.mattr.global",
18            "query": [
19                {
20                    "type": "QueryByExample",
21                    "credentialQuery": [
22                        {
23                            "reason": "Please provide your certificate.",
24                            "example": {
25                                "type": "CourseCredential",
26                                "@context": [
27                                    "https://www.w3.org/2018/credentials/v1",
28                                    "https://mattr.global/contexts/vc-extensions/v2",
29                                    "https://schema.org"
30                                ],
31                                "trustedIssuer": [
32                                    {
33                                        "issuer": "did:web:organization.com",
34                                        "required": true
35                                    }
36                                ]
37                            },
38                            "required": true
39                        }
40                    ]
41                }
42            ],
43            "challenge": "GW8FGpP6jhFrl37yQZIM6w"
44        }
45    },
46    "didcommUri": "didcomm://https://YOUR_TENANT_URL/v2/credentials/web-semantic/presentations/requests/38d9ca70-8b61-48c3-9efc-b67d97410743/didcommuri"
47}

  • id: Used by your tenant to uniquely identify this presentation request.

  • callbackUrl: As defined in the request.

  • request:

    • id: Used by your tenant to uniquely identify this presentation request.

    • type: Indicates request type (queryByFrame or queryByExample).

    • from: Verifier's DID.

    • created_time: Request creation time (Unix time).

    • expires_time: Request expiry time (Unix time) as defined in the request.

    • reply_url: The URL to forward the response to. This is a MATTR VII endpoint which would relay the response to the defined callbackurl.

    • reply_to: This is the DID the response message will be sent to.

  • didcommUri: This is the presentation request URI. It will be used as communication protocol for the exchange between your MATTR VII tenant and the digital wallet.

What's next?

Once your presentation request is created, continue to sending it to the holder.

Remember that presentation requests are removed as they expire. Make sure you set expiresTime values that enable testing.