Guides
Credential issuance
Direct
Compact Credential

How to issue a Compact Credential (Direct issuance)

Compact credentials represent claims of data that can be cryptographically proven as authentic while being compact enough to fit inside a QR code.

This guide will show you how to create and format a new Compact or Compact Semantic Credential.

This guide can be used to create both Compact and Compact Semantic Credentials. Any differences in the workflow are highlighted throughout the guide.

Prerequisites

  • DIDs:
    • Issuer DID: This is a did:web that identifies the issuer who attests the claims in the credential are accurate.
      • Refer to Create a did:web if you need assistance in creating one.
      • You can only sign a Compact Credential using DIDs with a P-256 key type. MATTR VII creates did:webs with this key type (and others) by default.
  • Claim values: The claims you wish to include in the credential. This is the information attested by the issuer.
  • The identifier of the desired PDF, Apple digital pass or Google digital pass template.

Overview

Direct issuance of a Compact Credential comprises the following steps:

  1. Sign the Compact Credential.
  2. Format the signed Compact Credential.
  3. Share the formatted credential.

Sign the Compact Credential

The request to sign the credential is different when you're signing a Compact or Compact Semantic Credential.

Request

Make a request of the following structure to create and sign a new Compact Credential:

HTTP
POST /v2/credentials/compact/sign
Request body
JSON
{
    "payload": {
        "iss": "did:web:learn.vii.au01.mattr.global",
        "nbf": 1704099600,
        "exp": 1767258000,
        "type": "Course Credential",
        "name": "Emma Jane Tasma",
        "code": "HS.278",
        "certificationName": "Working at Heights",
        "certificationLevel": "Level 4",
        "issuerName": "Advanced Safety Training",
        "expiry": "2026-01-01"
    },
    "revocable": true,
    "isRevoked": false
}
  • iss : Use the Issuer DID. This must be a publicly available and resolvable did:web for the credential to be valid and verifiable.
  • nbf : Not before. When set, credential verification will fail if the current time is earlier than the nbf value. Must be expressed as a Unix timestamp.
  • exp : Expiry. When set, credential verification will fail if the current time is later than the exp value. Must be expressed as a Unix timestamp.
  • type : Credential type.
  • name : Example for a custom claim.
  • code : Example for a custom claim.
  • certificationName : Example for a custom claim.
  • certificationLevel : Example for a custom claim.
  • issuerName : Example for a custom claim.
  • revocable : When set to true, the signed credential can later be revoked. When set to false, the credential cannot be revoked. Defaults to false.
  • isRevoked: When set to true, the signed credential is issued as revoked, and must be unrevoked to become valid. If isRevoked is provided (e.g. set to either true or false), revocable must be set to true. Defaults to false.

Response

JSON
{
    "id": "bKcrxojFSuSZvI5qhKInxA",
    "decoded": {
        "iss": "did:web:learn.vii.au01.mattr.global",
        "nbf": 1704099600,
        "type": "Course Credential",
        "exp": 1767258000,
        "name": "Emma Jane Tasma",
        "code": "HS.278",
        "certificationName": "Working at Heights",
        "certificationLevel": "Level 4",
        "issuerName": "Advanced Safety Training",
        "status": {
            "index": 3,
            "url": "https://learn.vii.au01.mattr.global/v2/credentials/compact/revocation-lists/887cd140-e4d7-4518-b70f-305b23778848"
        },
        "jti": "bKcrxojFSuSZvI5qhKInxA"
    },
    "encoded": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
}
  • id : Unique credential identifier. This is required when revoking a credential.
  • decoded : This is the decoded version of the credential. It includes all the information provided in the request, with the addition of the following elements:
    • status : If revocable was set to true in the request, this object is used to provide information required for revocation:
      • index : This indicates the index of this specific credential within the revocation list.
      • url : References the revocation List which holds the revocation status for this specific credential.
    • jti : This JWT ID identifies this credential and is identical to the id element. When revocable is set to true, this value is persisted on the tenant.
  • encoded : The base32 encoded string representation of the Compact Credential. CSC stands for COSE Sign Compact profile. You will use this element to convert the credential into a format that can be shared with a holder.

Format the signed Compact Credential

Once the Compact Credential is signed, you can render it in one of several formats before sharing it.

Format a Compact Credential as a QR Code

Request

Make a request of the following structure to format a Compact Credential as a QR code:

HTTP
POST /v2/credentials/compact/qrcode

You can make a similar request to a different endpoint to format a Compact Semantic Credential as a QR code:

HTTP
POST /v2/credentials/compact-semantic/qrcode
Request body
JSON
{
  "payload": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU",
  "width": 800
}
  • payload : Use the encoded element from the response obtained when signing the Compact Credential.
  • width : Optionally specify the desired width of the output QR code. When no width is specified MATTR VII will generate a QR code with an optimised width based on the size of the payload. Maximal value is 1000px.
Response

The response includes a QR code as a PNG file. This QR code contains the encoded credential and can be shared with the intended holder.

Errors

If the provided payload is invalid, the API will return one of the following errors:

  • 400 :
    • Payload is not a string.
    • Payload does not match a Compact Credential profile.
    • The credential has expired.
    • Unable to validate or decode the payload.
    • Generated QR code is larger than the provided width.
  • 413 :
    • The payload is too large to be stored in a QR code.

Share the formatted credential

Now that you have the credential rendered in the required format, you can share it with its intended holder.

Share the QR code image using your preferred communication channel (e.g. e-mail, messaging platform, etc.).

Retrieve a policyPDF