Learn

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 

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact/verify
json
Copy to clipboard.
1{
2  "payload": "CSC:/1/2KCE3IQEJB5DCMSMGZDHUUYBE2QFSAL5VMAXQNDENFSDU53FMI5G2YLUORZC2ZDJMR3WKYRNORSXG5BONZSXI3DJMZ4S4YLQOA5EIRKWHJWG6YLEORSXG5DFOICBVFP2YYZAKGS2L74K4ZDOMFWWK32FNVWWCICKMFXGKICUMFZW2YLEMNXWIZLGJBJS4MRXHBYWGZLSORUWM2LDMF2GS33OJZQW2ZLSK5XXE23JNZTSAYLUEBEGK2LHNB2HG4TDMVZHI2LGNFRWC5DJN5XEYZLWMVWGOTDFOZSWYIBUNJUXG43VMVZE4YLNMV4BQQLEOZQW4Y3FMQQFGYLGMV2HSICUOJQWS3TJNZTWMZLYOBUXE6LKGIYDENRNGAYS2MBRHIAACAAAUIBBSAS4AN4IA2DUORYHGORPF5WG6YLEFV2GK43UNFXGOLTQNRQXIZTPOJWS4ZDFOYXG2YLUORZGYYLCOMXGS3ZPMNXXEZJPOYZC6Y3SMVSGK3TUNFQWY4ZPMNXW24DBMN2C64TFOZXWGYLUNFXW4LLMNFZXI4ZPMMYGEY3GMMZDALJRGUYTILJUHA4TSLLBGQ2TCLJZGNRGGY3GHFQTON3BHED5QQCQGNQJXK7NYZDAXN3JOR6WEYYHOBMEBAUOXZHFGWFPR4LR6V3KLIFH25CNPBZB5LH2AW42YW3KSNPD2DPBKSWN3CLVMOZOJGUKNCNDSHR6X5RRGRJ562P3HEMXUQK367MBGPYA",
3  "checkRevocation": true
4}

Response 

json
Copy to clipboard.
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 

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/verify
json
Copy to clipboard.
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 

json
Copy to clipboard.
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