Skip to main content

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 Sovrin API 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​

POST https://api.sovrin.one/core/v2/credentials/compact/verify 
{
  "payload": "CSC:/1/2KCE3IQEJB5DCMSMGZDHUUYBE2QFSAL5VMAXQNDENFSDU53FMI5G2YLUORZC2ZDJMR3WKYRNORSXG5BONZSXI3DJMZ4S4YLQOA5EIRKWHJWG6YLEORSXG5DFOICBVFP2YYZAKGS2L74K4ZDOMFWWK32FNVWWCICKMFXGKICUMFZW2YLEMNXWIZLGJBJS4MRXHBYWGZLSORUWM2LDMF2GS33OJZQW2ZLSK5XXE23JNZTSAYLUEBEGK2LHNB2HG4TDMVZHI2LGNFRWC5DJN5XEYZLWMVWGOTDFOZSWYIBUNJUXG43VMVZE4YLNMV4BQQLEOZQW4Y3FMQQFGYLGMV2HSICUOJQWS3TJNZTWMZLYOBUXE6LKGIYDENRNGAYS2MBRHIAACAAAUIBBSAS4AN4IA2DUORYHGORPF5WG6YLEFV2GK43UNFXGOLTQNRQXIZTPOJWS4ZDFOYXG2YLUORZGYYLCOMXGS3ZPMNXXEZJPOYZC6Y3SMVSGK3TUNFQWY4ZPMNXW24DBMN2C64TFOZXWGYLUNFXW4LLMNFZXI4ZPMMYGEY3GMMZDALJRGUYTILJUHA4TSLLBGQ2TCLJZGNRGGY3GHFQTON3BHED5QQCQGNQJXK7NYZDAXN3JOR6WEYYHOBMEBAUOXZHFGWFPR4LR6V3KLIFH25CNPBZB5LH2AW42YW3KSNPD2DPBKSWN3CLVMOZOJGUKNCNDSHR6X5RRGRJ562P3HEMXUQK367MBGPYA",
  "checkRevocation": true
}

Response​

{
    "verified": true,
    "decoded": {
        "iss": "did:web:organization.com",
        "exp": 2516239922,
        "nbf": 1516239022,
        "status": {
            "url": "https://api.sovrin.one/core/v2/credentials/compact/revocation-lists/c0bcfc20-1514-4899-a451-93bccf9a77a9",
            "index": 604
        },
        "name": "Emma Jane Tasma",
        "code": "HS.278",
        "certificationName": "Working at Heights",
        "certificationLevel": "Level 4",
        "issuerName": "Advanced Safety Training",
        "expiry": "2026-01-01",
        "jti": "M2Cbq-3GRgu3aXR9YmMHcA"
    }
}

Semantic compact credential​

Request​

POST https://api.sovrin.one/core/v2/credentials/compact-semantic/verify
{
  "payload": "CSS:/1/2KCE3IQEJB5DCMSMGZDHUUYBE2QFSAPOU4AXQNDENFSDU53FMI5G2YLUORZC2ZDJMR3WKYRNORSXG5BONZSXI3DJMZ4S4YLQOA5EIRKWHJWG6YLEORSXG5DFOICBVFP2YYZAKGS2L74K4Y3KORU7OB6YIBIC4L6VUL3MWR4TXVYGTLFKBBZDWYTWMORWQQDDN5XHIZLYOSAXQJTIOR2HA4Z2F4XXO53XFZ3TGLTPOJTS6MRQGE4C6Y3SMVSGK3TUNFQWY4ZPOYYWI5DZOBSYC5CWMVZGSZTJMFRGYZKDOJSWIZLOORUWC3DRMNZGKZDFNZ2GSYLMKN2WE2TFMN2KMZDOMFWWK32FNVWWCICKMFXGKICUMFZW2YLEMNXWIZLGJBJS4MRXHBYWGZLSORUWM2LDMF2GS33OJZQW2ZLSK5XXE23JNZTSAYLUEBEGK2LHNB2HG4TDMVZHI2LGNFRWC5DJN5XEYZLWMVWGOTDFOZSWYIBUNJUXG43VMVZE4YLNMV4BQQLEOZQW4Y3FMQQFGYLGMV2HSICUOJQWS3TJNZTWMZLYOBUXE6LKGIYDENRNGAYS2MBRHIAACAAAUIBBQRIDPCEWQ5DUOBZTULZPNRXWCZBNORSXG5DJNZTS44DMMF2GM33SNUXGIZLWFZWWC5DUOJWGCYTTFZUW6L3DN5ZGKL3WGIXWG4TFMRSW45DJMFWHGL3DN5WXAYLDOQWXGZLNMFXHI2LDF5ZGK5TPMNQXI2LPNYWWY2LTORZS6ZLFME4DOZLGMQWTCZTDGEWTIY3DGMWTQNLDGAWTEZTEGQ4TAY3GGU2GCNSYIDOEQ7VGMYLTMHDQ662S44UAKVWTCCS5NI5GJAAOT2LSMVKLZP2MIK6UA5F5UWUIN4XYDCKIEDVEAXLCRQ2TCBRKP5ZQYW3W3W3DB4WJ",
  "checkRevocation": true
}

when verifying a revoked credential, set checkRevocation to true. The response returns verified as false with decoded payload.

Response​

{
    "verified": false,
    "reason": {
        "type": "Revoked",
        "message": "Credential has been revoked"
    },
    "decoded": {
        "iss": "did:web:organization.com",
        "exp": 2516239922,
        "nbf": 1516239022,
        "status": {
            "url": "https://api.sovrin.one/core/v2/credentials/compact-semantic/revocation-lists/eea87efd-1fc1-4cc3-85c0-2fd490cf54a6",
            "index": 69
        },
        "vc": {
            "@context": [
                "https://www.w3.org/2018/credentials/v1"
            ],
            "type": [
                "VerifiableCredential"
            ],
            "credentialSubject": {
                "name": "Emma Jane Tasma",
                "code": "HS.278",
                "certificationName": "Working at Heights",
                "certificationLevel": "Level 4",
                "issuerName": "Advanced Safety Training",
                "expiry": "2026-01-01"
            }
        },
        "jti": "urn:uuid:2e2fd5a2-f6cb-4793-bd70-69acaa08723b"
    }
}

Request by PDF or image​

It is possible to capture the entire PDF or image of a document and send it to the Sovrin API Compact Credential Verify API by specifying the Content-Type to multipart/form-data.

In the request include the binary PDF or image file.

The Sovrin API 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