Table of Contents
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:
POST https://tenant.platform.mattr.global/v1/presentations/templates
Request
{"domain":"tenant.platform.mattr.global","name":"certificate-presentation","query":[{"type": "QueryByExample","credentialQuery": [{"required": true,"reason": "Please provide your certificate.","example": {"@context": ["https://schema.org"],"type": "Course","trustedIssuer": [{"required": true,"issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"}]}}]}]}
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:
@context
is the JSON-LD schema, which should match the schema as defined in the credential that is being requested.type
is the credential type that the Mobile Wallet will use to find matching credentials that it holds.- The
issuer
intrustedIssuer
filters which Credentials will be acceptable. An employer, for instance, might only accept the public DIDs of certain universities.
Response
{"id": "f95e71b0-9bdf-11ea-aec9-3b5c35fc28c8","domain": "tenant.platform.mattr.global","query": [{"type": "QueryByExample","credentialQuery": [{"required": true,"reason": "Please provide your certificate.","example": {"@context": ["https://schema.org"],"type": "Course","trustedIssuer": [{"required": true,"issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"}]}}]}],"name": "certificate-presentation"}
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.
Request
{"domain":"tenant.platform.mattr.global","name":"zkp-certificate-presentation","query": [{"type":"QueryByFrame","credentialQuery":[{"reason": "Please provide your educational award and surname from your Certificate","frame":{"@context":["https://www.w3.org/2018/credentials/v1","https://w3id.org/vc-revocation-list-2020/v1","https://schema.org"],"type": "VerifiableCredential","credentialSubject":{"@explicit":true,"educationalCredentialAwarded":{ },"familyName":{ }}},"trustedIssuer":[{"issuer":"did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v","required":true}],"required":true}]}]}
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:
@context
is 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/v1
and revocable credential must containhttps://w3id.org/vc-revocation-list-2020/v1
.type
The Wallet will use this to match credentials that it holds, however the current implementation requires that this is the firsttype
so will always need to be set toVerifiableCredential
.- the
credentialSubject
states which claims from the credential are required for the presentation, only these claims will need to be sent to the verifier. - The
issuer
intrustedIssuer
filters 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
{"id": "6d597607-d64d-4209-8d2e-7e5a4587bbc8","name": "zkp-certificate-presentation","domain": "tenant.platform.mattr.global","query": [{"type": "QueryByFrame","credentialQuery": [{"reason": "Please provide your educational award and surname from your Certificate","frame": {"@context": ["https://www.w3.org/2018/credentials/v1","https://w3id.org/vc-revocation-list-2020/v1","https://schema.org"],"type": "VerifiableCredential","credentialSubject": {"@explicit": true,"educationalCredentialAwarded": {},"familyName": {}}},"trustedIssuer": [{"issuer": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v","required": true}],"required": true}]}]}
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.