Direct verification of Compact Credentials

This guide will step through how to make a direct API call to verify a Compact or Compact Semantic Credential. You can use this API to verify a credential presented as either a PDF document, an image file or an encoded string.

Standard checks performed on all verification requests:

• Conformance of the string and encoded data. All string representations of Compact Credentials must be prefixed with CSC/1.

• Decoded payload structure is a valid Compact Credential.

• Issuer DID can be used to resolve its did.json document.

• Public key from issuer's did.json document validates the proof signature, confirming the credential has not been tampered with.

Optional parameter checks:

• Credential is issued by a trusted issuer.

• Current time is after the beginning of the credential validity period.

• Current time is not after the end of the credential validity period.

• Credential has not been revoked.

Prerequisites

• Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

• A signed Compact or Compact Semantic Credential encoded as a string. This will be the encoded element of the credential issuance response.

  or

• A signed Compact or Compact Semantic Credential encoded as a QR code and represented as a PDF document or an image file:

  • File size can be 1MB or under. Larger files are rejected with a 413 error. 

  • Only the first page of PDF documents is processed.  

  • Image files must contain a QR code of sufficient quality and resolution. This depends on many factors such as the size of the QR relative to the image, and whether the image had been processed in any way.

  • For optimal performance, ensure that only a single QR code is present on the file. 

Request

Make a request of the following structure to verify a Compact Credential:

1POST https://YOUR_TENANT_URL/core/v2/credentials/compact/verify

You can make a similar request to a different endpoint to verify a Compact Semantic Credential:

1POST https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/verify

If you are verifying a credential presented as a PDF document or image file, specify the request Content-Type to multipart/form-data and include the binary PDF or image file. The QR code in the document/image is read and its contents processed as the credential. 

Request body

1{
2  "payload": "CSC:/1/2KCE3IQEJB5DCMSLN5KWKZABE2QFQRVDAF4CIZDJMQ5HOZLCHIYDGOJUFUYTENJNGIZTOLJVGIWTCMJQFZXGO4TPNMXGS33ENZQW2ZLEJJXWQ3QH3BAFB3LISHKGQ2KBJ6Q35NXZFD6LGZ2YIAYHZAKCF7NKTIUZUTZQ3PWDBALAWVRG5XL2H4P4WFK25X3Y5X5RTN7NOZUST67KLCEFS3EPXQU5KM7VUGOPXJLQ6K5U676PMQNWRZCZ",
3  "trustedIssuers": [
4    "did:web:example.com"
5  ],
6  "assertValidFrom": true,
7  "assertValidUntil": true,
8  "checkRevocation": true
9}

• payload: Use the encoded element from the response obtained when creating a Compact or Compact Semantic Credential.

• trustedIssuers (optional): When you include issuers' DIDs in this array, credentials will only be verified if their iss value matches one of these DIDs. You can include multiple trusted issuers, separated by commas.

• assertValidFrom: MATTR VII validates the credential's nbf (not before) field by default, so that credentials that have a future not before date will not be verified. When this field is set to false, credentials can be verified even when their nbf date is in the future.

• assertValidUntil: MATTR VII validates the credential's exp (expiry) field by default, so that expired credentials will not be verified. When this field is set to false, credentials can be verified even when their exp date has passed.

• checkRevocation: MATTR VII checks the credential revocation status by default, so that revoked credentials will not be verified. When this field is set to false, credentials can be verified even when they had been revoked.

Response 

1{
2    "verified": true,
3    "decoded": {
4        "iss": "did:web:example.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        "jti": "M2Cbq-3GRgu3aXR9YmMHcA"
17    }
18}

• verified: Indicates whether the verification status is true or false.

• decoded: Includes the decoded payload.

For responses that show the verified status to be false, a further error body is returned with more details about the error:  

• The credential is not issued by a trusted issuer.

• The issuer public key is invalid.

• The credential signature is invalid.

• The credential has expired (exp is in the past).

• The credential has been revoked.

• The credential is not active (nbf is in the future).

Payloads that fail to decode will return standard HTTP status responses:  

• 400:

  • Payload is not a string.

  • Payload does not match a Compact Credential profile.

  • Unable to validate or decode the payload.

• 415: Unsupported media type.

• 413: Payload too large.