How to issue a CWT credential directly
CWT 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 CWT or Semantic CWT credential.
This guide can be used to create both CWT and Semantic CWT 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.- You can only sign a CWT credential using DIDs with a
P-256
key type. MATTR VII createsdid:web
s with this key type (and others) by default.
- You can only sign a CWT credential using DIDs with a
- Issuer DID: This is a
- 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 CWT credential comprises the following steps:
Sign the CWT credential
The request to sign the credential is different when you're signing a CWT or Semantic CWT Credential.
Make a request of the following structure to create and sign a new CWT credential:
POST /v2/credentials/compact/sign
{
"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 resolvabledid: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 totrue
, the signed credential can later be revoked. When set tofalse
, the credential cannot be revoked. Defaults tofalse
.isRevoked
: When set totrue
, the signed credential is issued as revoked, and must be unrevoked to become valid. IfisRevoked
is provided (e.g. set to eithertrue
orfalse
),revocable
must be set totrue
. Defaults tofalse
.
Response
{
"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
: Ifrevocable
was set totrue
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 theid
element. Whenrevocable
is set totrue
, this value is persisted on the tenant.
encoded
: The base32 encoded string representation of the CWT credential.CSC
stands forCOSE Sign Compact
profile. You will use this element to convert the credential into a format that can be shared with a holder.
Semantic CWT Credentials represent claims inside a W3C Verifiable Credential data model which is then signed as a CWT credential.
Make a request of the following structure to create and sign a new Semantic CWT credential:
POST /v2/credentials/compact-semantic/sign
{
"payload": {
"iss": "did:web:learn.vii.au01.mattr.global",
"nbf": 1704099600,
"exp": 1767258000,
"vc": {
"type": "Course Credential",
"credentialSubject": {
"name": "Emma 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 resolvabledid:web
for the credential to be valid and verifiable.nbf
: Set the Unix epochtime and date the credential will be active from (Unix Epoch time) .exp
: Set the time and date the credential will expire (Unix Epoch time).vc
: This object includes all custom claims in the credential. These must comply with the W3C Verifiable Credentials Data Model and its vocabulary context.revocable
: When set totrue
, the signed credential can later be revoked. When set tofalse
, the credential cannot be revoked. Defaults tofalse
.isRevoked
: When set totrue
, the signed credential is issued as revoked, and must be unrevoked to become valid. IfisRevoked
is provided (e.g. set to eithertrue
orfalse
),revocable
must be set totrue
. Defaults tofalse
.
Response
{
"id": "urn:uuid:78e19496-8521-424b-8315-35fb1ecaf681",
"decoded": {
"iss": "did:web:learn.vii.au01.mattr.global",
"nbf": 1704099600,
"exp": 1767258000,
"vc": {
"type": ["VerifiableCredential", "Course Credential"],
"@context": ["https://www.w3.org/2018/credentials/v1"],
"credentialSubject": {
"name": "Emma Tasma",
"code": "HS.278",
"certificationName": "Working at Heights",
"certificationLevel": "Level 4",
"issuerName": "Advanced Safety Training",
"expiry": "2026-01-01"
}
},
"status": {
"index": 0,
"url": "https://learn.vii.au01.mattr.global/v2/credentials/compact-semantic/revocation-lists/1fe00d6c-904f-497e-bbe1-a3cfdc0b8368"
},
"jti": "urn:uuid:78e19496-8521-424b-8315-35fb1ecaf681"
},
"encoded": "CSS:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSAOZUYAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQMJ3GHI3IIBRW63TUMV4HJALYEZUHI5DQOM5C6L3XO53S45ZTFZXXEZZPGIYDCOBPMNZGKZDFNZ2GSYLMOMXXMMLEOR4XAZMCORLGK4TJMZUWCYTMMVBXEZLEMVXHI2LBNRYUG33VOJZWKICDOJSWIZLOORUWC3DRMNZGKZDFNZ2GSYLMKN2WE2TFMN2KMZDOMFWWK2SFNVWWCICUMFZW2YLEMNXWIZLGJBJS4MRXHBYWGZLSORUWM2LDMF2GS33OJZQW2ZLSK5XXE23JNZTSAYLUEBEGK2LHNB2HG4TDMVZHI2LGNFRWC5DJN5XEYZLWMVWGOTDFOZSWYIBUNJUXG43VMVZE4YLNMV4BQQLEOZQW4Y3FMQQFGYLGMV2HSICUOJQWS3TJNZTWMZLYOBUXE6LKGIYDENRNGAYS2MBRAQNGSVRXSA5AAAIAACRAEAADPB7GQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UFVZWK3LBNZ2GSYZPOJSXM33DMF2GS33OFVWGS43UOMXTCZTFGAYGINTDFU4TANDGFU2DSN3FFVRGEZJRFVQTGY3GMRRTAYRYGM3DQB6YIBIHRYMUS2CSCQSLQMKTL6Y6ZL3ICWCAUPGIGEOOWODF77V7ZJPVLGAQC2ZUP7MASXIRTIRRPOIIBKNHKZ4LHROPWBPBCYTKA3GXWIRD736HIJNQENTSFUYIPQ77BG4ZPCTXYIY"
}
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:type
: MATTR VII automatically injectsVerifiableCredential
for all Semantic CWT credentials.@context
: MATTR VII automatically injectshttps://www.w3.org/2018/credentials/v1
for all Semantic CWT credentials.status
: Ifrevocable
was set totrue
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 theid
element. Whenrevocable
is set totrue
, this value is persisted on the tenant.
encoded
: The base32 encoded string representation of the Semantic CWT credential.CSS
stands forCOSE Sign Semantic
profile. You will use this element to convert the credential into a format that can be shared with a holder.
Format the signed CWT credential
Once the CWT credential is signed, you can render it in one of several formats before sharing it.
Make a request of the following structure to format a CWT credential as a QR code:
POST /v2/credentials/compact/qrcode
You can make a similar request to a different endpoint to format a Semantic CWT credential as a QR code:
POST /v2/credentials/compact-semantic/qrcode
{
"payload": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU",
"width": 800
}
payload
: Use theencoded
element from the response obtained when signing the CWT 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 CWT credential format.
- 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.
Make a request of the following structure to format a CWT credential as a PDF:
POST /v2/credentials/compact/pdf
You can make a similar request to a different endpoint to format a Semantic CWT credential as a PDF:
POST /v2/credentials/compact-semantic/pdf
{
"templateId": "ccad3b98-7086-4556-9e19-9e2aa6ca5c5b",
"payload": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
}
templateId
: Use theid
of the PDF template you wish to use to format this credential.payload
: Use theencoded
element from the response obtained when signing the CWT credential.
Response
The response includes a PDF document with the information from the credential formatted according to the PDF template.
Errors
Bad request (400) Errors may occur in the following scenarios:
- Payload is not a string.
- Payload does not match a CWT credential format.
- The credential has expired.
- Unable to validate or decode the payload.
- The PDF template does not exist.
- The decoded payload doesn't include a claim required for the PDF template.
Your Apple developer certificates must be valid when attempting to format CWT credentials as Apple digital passes.
Make a request of the following structure to format a CWT credential as an Apple digital pass:
POST /v2/credentials/compact/digital-pass/apple
You can make a similar request to a different endpoint to format a Semantic CWT credential as an Apple digital pass:
POST /v2/credentials/compact-semantic/digital-pass/apple
{
"templateId": "1b04f0ee-8e3e-4153-a0e0-8603a10e7f0a",
"payload": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
}
templateId
: Use theid
of the Apple digital pass template you wish to use to format this credential.payload
: Use theencoded
element from the response obtained when signing the CWT credential.
Response
The response includes a signed bundle .pkpass
file (binary format).
Errors
Bad request (400) Errors may occur in the following scenarios:
- Payload is not a string.
- Payload does not match a CWT credential format.
- The credential has expired.
- Unable to validate or decode the payload.
- Apple developer account credentials are missing or incorrect.
- The template does not exist or is incorrectly defined.
- Required
config.json
fields are not defined. - The file name contains a special character that is not supported by the Apple pass template endpoint.
- The decoded payload is missing a required value for
pass.json
.
Your Google developer certificates must be valid when attempting to format CWT credentials as Google digital passes.
Make a request of the following structure to format a CWT credential as a Google digital pass:
POST /v2/credentials/compact/digital-pass/google
You can make a similar request to a different endpoint to format a Semantic CWT credential as a Google digital pass:
POST /v2/credentials/compact-semantic/digital-pass/google
{
"templateId": "1b04f0ee-8e3e-4153-a0e0-8603a10e7f0a",
"payload": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
}
templateId
: Use theid
of the Google digital pass template you wish to use to format this credential.payload
: Use theencoded
element from the response obtained when signing the CWT credential.
Response
{
"redirectTo": "https://pay.google.com/gp/v/save/ejqEeFUtiFRF2t_0hXelmd1TDaeoPES091NT7LBiDvrmKpYPrOlhBfeSKOaA"
}
redirectTo
: This is the URL where the digital pass is available to download.
Errors
Bad request (400) Errors may occur in the following scenarios:
- Payload is not a string.
- Payload does not match a CWT credential format.
- The credential has expired.
- Unable to validate or decode the payload.
- Google account credentials are missing or incorrect
- The template does not exist or is incorrectly defined.
- The decoded payload doesn't include a field required in
template.json
.
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.).
Share the PDF document using your preferred communication channel (e.g. e-mail, messaging platform, etc.).
Share the .pkpass
file using your preferred communication channel (e.g. e-mail, messaging
platform, etc.). The recipient will be able to save the file into their Apple wallet.
You can use the "Add to Apple Wallet" badge as a visual cue. Download files
from Add to Apple Wallet badge
guidelines.
Share the download URL using your preferred communication channel (e.g. e-mail, messaging platform, etc.). The recipient can use the link to download the credential and save it into their Google wallet.
You can use the "Add to Google Wallet" badge as a visual cue. Download files
from Google Wallet brand
guidelines.
How would you rate this page?