Verify compact credentials
Introduction
This guide will step through how to verify a compact or semantic compact credential presented as either a PDF, image file or encoded string. The response of a verified compact credential contains a verified status of the credential along with the decoded payload.
Prerequisites
You need the following in order to proceed with this tutorial:
Access to the MATTR VII APIs
A signed and encoded compact or semantic compact credential represented as a string, or
A signed and encoded compact or semantic compact credential represented as a digital PDF file or an image
If you’re experiencing any difficulties, contact us.
Request by encoded string
The payload in the request is the encoded & signed Compact Credential represented as a string.
trustedIssuers is an optional array of strings containing issuer DIDs
nbf and exp are validated by default, with an option to opt-out assertExpiry assertNotBefore
Revocation is validated by default, with an option to opt-out checkRevocation.
Compact credential
Request
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact/verify
1{
2 "payload": "CSC:/1/2KCE3IQEJB5DCMSMGZDHUUYBE2QFSAL5VMAXQNDENFSDU53FMI5G2YLUORZC2ZDJMR3WKYRNORSXG5BONZSXI3DJMZ4S4YLQOA5EIRKWHJWG6YLEORSXG5DFOICBVFP2YYZAKGS2L74K4ZDOMFWWK32FNVWWCICKMFXGKICUMFZW2YLEMNXWIZLGJBJS4MRXHBYWGZLSORUWM2LDMF2GS33OJZQW2ZLSK5XXE23JNZTSAYLUEBEGK2LHNB2HG4TDMVZHI2LGNFRWC5DJN5XEYZLWMVWGOTDFOZSWYIBUNJUXG43VMVZE4YLNMV4BQQLEOZQW4Y3FMQQFGYLGMV2HSICUOJQWS3TJNZTWMZLYOBUXE6LKGIYDENRNGAYS2MBRHIAACAAAUIBBSAS4AN4IA2DUORYHGORPF5WG6YLEFV2GK43UNFXGOLTQNRQXIZTPOJWS4ZDFOYXG2YLUORZGYYLCOMXGS3ZPMNXXEZJPOYZC6Y3SMVSGK3TUNFQWY4ZPMNXW24DBMN2C64TFOZXWGYLUNFXW4LLMNFZXI4ZPMMYGEY3GMMZDALJRGUYTILJUHA4TSLLBGQ2TCLJZGNRGGY3GHFQTON3BHED5QQCQGNQJXK7NYZDAXN3JOR6WEYYHOBMEBAUOXZHFGWFPR4LR6V3KLIFH25CNPBZB5LH2AW42YW3KSNPD2DPBKSWN3CLVMOZOJGUKNCNDSHR6X5RRGRJ562P3HEMXUQK367MBGPYA",
3 "checkRevocation": true
4}
Response
1{
2 "verified": true,
3 "decoded": {
4 "iss": "did:web:organization.com",
5 "exp": 2516239922,
6 "nbf": 1516239022,
7 "status": {
8 "url": "https://YOUR_TENANT_URL/core/v2/credentials/compact/revocation-lists/c0bcfc20-1514-4899-a451-93bccf9a77a9",
9 "index": 604
10 },
11 "name": "Emma Jane Tasma",
12 "code": "HS.278",
13 "certificationName": "Working at Heights",
14 "certificationLevel": "Level 4",
15 "issuerName": "Advanced Safety Training",
16 "expiry": "2026-01-01",
17 "jti": "M2Cbq-3GRgu3aXR9YmMHcA"
18 }
19}
Semantic compact credential
Request
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/verify
1{
2 "payload": "CSS:/1/2KCE3IQEJB5DCMSMGZDHUUYBE2QFSAPOU4AXQNDENFSDU53FMI5G2YLUORZC2ZDJMR3WKYRNORSXG5BONZSXI3DJMZ4S4YLQOA5EIRKWHJWG6YLEORSXG5DFOICBVFP2YYZAKGS2L74K4Y3KORU7OB6YIBIC4L6VUL3MWR4TXVYGTLFKBBZDWYTWMORWQQDDN5XHIZLYOSAXQJTIOR2HA4Z2F4XXO53XFZ3TGLTPOJTS6MRQGE4C6Y3SMVSGK3TUNFQWY4ZPOYYWI5DZOBSYC5CWMVZGSZTJMFRGYZKDOJSWIZLOORUWC3DRMNZGKZDFNZ2GSYLMKN2WE2TFMN2KMZDOMFWWK32FNVWWCICKMFXGKICUMFZW2YLEMNXWIZLGJBJS4MRXHBYWGZLSORUWM2LDMF2GS33OJZQW2ZLSK5XXE23JNZTSAYLUEBEGK2LHNB2HG4TDMVZHI2LGNFRWC5DJN5XEYZLWMVWGOTDFOZSWYIBUNJUXG43VMVZE4YLNMV4BQQLEOZQW4Y3FMQQFGYLGMV2HSICUOJQWS3TJNZTWMZLYOBUXE6LKGIYDENRNGAYS2MBRHIAACAAAUIBBQRIDPCEWQ5DUOBZTULZPNRXWCZBNORSXG5DJNZTS44DMMF2GM33SNUXGIZLWFZWWC5DUOJWGCYTTFZUW6L3DN5ZGKL3WGIXWG4TFMRSW45DJMFWHGL3DN5WXAYLDOQWXGZLNMFXHI2LDF5ZGK5TPMNQXI2LPNYWWY2LTORZS6ZLFME4DOZLGMQWTCZTDGEWTIY3DGMWTQNLDGAWTEZTEGQ4TAY3GGU2GCNSYIDOEQ7VGMYLTMHDQ662S44UAKVWTCCS5NI5GJAAOT2LSMVKLZP2MIK6UA5F5UWUIN4XYDCKIEDVEAXLCRQ2TCBRKP5ZQYW3W3W3DB4WJ",
3 "checkRevocation": true
4}
when verifying a revoked credential, set checkRevocation
to true. The response returns verified
as false with decoded payload.
Response
1{
2 "verified": false,
3 "reason": {
4 "type": "Revoked",
5 "message": "Credential has been revoked"
6 },
7 "decoded": {
8 "iss": "did:web:organization.com",
9 "exp": 2516239922,
10 "nbf": 1516239022,
11 "status": {
12 "url": "https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/revocation-lists/eea87efd-1fc1-4cc3-85c0-2fd490cf54a6",
13 "index": 69
14 },
15 "vc": {
16 "@context": [
17 "https://www.w3.org/2018/credentials/v1"
18 ],
19 "type": [
20 "VerifiableCredential"
21 ],
22 "credentialSubject": {
23 "name": "Emma Jane Tasma",
24 "code": "HS.278",
25 "certificationName": "Working at Heights",
26 "certificationLevel": "Level 4",
27 "issuerName": "Advanced Safety Training",
28 "expiry": "2026-01-01"
29 }
30 },
31 "jti": "urn:uuid:2e2fd5a2-f6cb-4793-bd70-69acaa08723b"
32 }
33}
Request by PDF or image
It is possible to capture the entire PDF or image of a document and send it to the MATTR VII Compact Credential Verify API by specifying the Content-Type to multipart/form-data
.
In the request include the binary PDF or image file.
The MATTR VII Compact Credential Verify API will process the file by:
Determining the file size, a maximum 1MB file is permitted to be uploaded, larger files will be rejected with a 413 error.
For PDF files, only the 1st page of the PDF is processed.
Images must contain a Compact Credential QR code of sufficient quality and resolution, this depends on many factors just as the size of the QR relative to the image, and if any other pre-processing has occurred on the image.
The server will scan the file looking for a QR code, this is deterministic but the order cannot be overridden, try to ensure that only a single QR code is present on the file.
The QR code is then read and the contents processed as a Compact Credential.
Not verified and other errors
In general, if the payload of the compact credential can be read and decoded, the API will return a 200 HTTP status and specify if the compact credential is verified using the Boolean flag.
For responses that show the verified status to be false, a further error body is returned with more details about the error, examples include:
The credential is not issued by a trusted issuer
The public key of the issuer is invalid
The signature of the credential is invalid
The credential is expired
The credential is revoked
The credential is not active
Payloads that fail to decode or that are too large will return 4xx HTTP status responses, examples include:
400 Failed to decode base32 payload
400 Unsupported payload
415 Unsupported media type
413 Payload Too Large