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: Unique transaction identifier. While you can use it as a transaction id element, consider that the challenge is part of the signed presentation request and it is not encrypted. Therefore, it should not be considered secure.

  • 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 is not present directly in the signed presentation request JWS. We recommend including a secret unique identifier in the URL to create a unique secured callback URL for each request which would make it hard to guess.

    • We also recommend for the callback endpoint to always respond 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.