How to issue a JSON credential (Direct issuance)

JSON credentials are based on the W3C Verifiable Credential data model for expressing cryptographically secure digital credentials on the web.

This guide will show you how to create a new JSON credential and share it with its intended holder.

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 JSON credential using DIDs with a ed25519 or bls12381g2 key type. MATTR VII creates did:webs with both of these key types by default.
- Subject DID: This is a did:key that identifies the intended holder of the credential. This DID must have a ed25519 key type and is usually retrieved from the intended holder’s digital wallet.
  - For testing it is recommended to use your MATTR Showcase Wallet DID (Settings > Advanced > Public DID) so that you can issue the credential to your own wallet.
  - In production environments you must have a secure way to obtain the holder’s digital wallet DID:
    - Use DID Auth for any new interactions.
    - Ask the user to share their wallet DID.
    - Request an existing credential as part of a verification workflow, and extract the DID from that interaction.
Credential structure:
- Credential type.
- JSON-LD claim names.
- Claim values: The claims you wish to include in the credential. This is the information attested by the issuer.

Overview

Direct issuance of a JSON credential comprises the following steps:

Sign the JSON credential.
Encrypt the signed credential.
Share the encrypted credential.

Sign the JSON credential

Request

Make a request of the following structure to create and sign a new JSON credential:

HTTP

POST /v2/credentials/web-semantic/sign

Request body

JSON

{
    "payload": {
        "name": "Course credential",
        "description": "Diploma in Management",
        "type": ["EducationalOccupationalCredential", "AlumniCredential"],
        "credentialSubject": {
            "id": "did:key:z6Mkr9f7o82NFLRFTTCWRR1GiZpca22Xf6YKo2zKThrZMA2w",
            "givenName": "Emma",
            "familyName": "Tasma",
            "alumniOf": "Zealopia University"
        },
        "credentialBranding": {
            "backgroundColor": "#860012",
            "watermarkImageUrl": "https://static.mattr.global/credential-assets/zealopia/web/watermark.svg"
        },
        "issuer": {
            "id": "did:web:learn.vii.au01.mattr.global",
            "name": "Zealopia Business Institute",
            "iconUrl": "https://static.mattr.global/credential-assets/zealopia/web/logo.svg",
            "logoUrl": "https://static.mattr.global/credential-assets/zealopia/web/icon.svg"
        },
        "expirationDate": "2024-02-01T08:12:38.156Z",
        "issuanceDate": "2023-02-01T08:12:38.156Z"
    },
    "proofType": "Ed25519Signature2018",
    "tag": "external-identifier",
    "persist": false,
    "revocable": true,
    "includeId": true
}

name : Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder’s digital wallet (see image below). Maximum length is 18 characters. Additional characters will not be displayed.
description : Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder’s digital wallet (see image below). Maximum length is 38 characters. Additional characters will not be displayed.
type : This array of credential types indicates what sort of information a credential holds. This is a unique identifier used to differentiate between various JSON credential types. MATTR VII automatically injects VerifiableCredential as the first value of this array, and you must include at least one additional value in the request payload.
credentialSubject :
- id : Insert the DID that identifies the intended holder and is associated with their digital wallet. This is what binds this credential to a specific holder.
- givenName : Example for a custom claim.
- familyName : Example for a custom claim.
- alumniOf : Example for a custom claim.
credentialBranding : Additional branding that will be applied to issued credentials:
- backgroundColor : Insert a colour hex code to use for the credential background color in the holder’s digital wallet (see image below).
- watermarkImageUrl : Insert a URL for a watermark image to be included as a pattern on the credential in the holder’s digital wallet (see image below):
  - Must be publicly available.
  - Must be 245x150 px in size.
  - svg, png and jpg files are supported, but svg is recommended.
  - If no watermark image is provided, a wave pattern is applied to the credentials by default.
  - Recommended maximum size for watermarkImageUrl is 150kb.
issuer :
- id : Use the DID that identifies the credential’s issuer, which attests the claims in the credential. This must be a publicly available and resolvable did:web for the credential to be valid and verifiable.
- name : Insert a meaningful name to indicate the issuer. This string is used when the credential is offered to the holder. It is also used on the bottom part of the credential when logoURL is not provided.
- logoURL : Insert a URL for a logo that is displayed on the bottom part of the credential (see image below). If no logo is provided, the issuer’s name and iconURL are used instead. The logo must meet the following criteria:
  - URL must be publicly available.
  - Must be 140x42 px in size.
  - svg, png and jpg files are supported, but svg is recommended. Raster images, whilst supported, are currently displayed at 1x resolution and may look pixelated on some devices.
  - Transparencies are allowed for svg or png images.
  - If no logo is provided, the first letter of the issuer name is displayed instead.
  - Recommended maximum size for logoURL is 50kb.
- iconURL : Insert a URL for an icon that is displayed next to the issuer’s name when the credential is offered to the holder. It is also displayed next to the issuer’s name on the bottom part of the credential when logoURL is not provided. When iconURL is not provided, the first letter from name is used instead. The icon must meet the following criteria:
  - URL must be publicly available.
  - Must be 32x32 px in size.
  - svg, png and jpg files are supported, but svg is recommended. Raster images, whilst supported, are currently displayed at 1x resolution and may look pixelated on some devices.
  - Transparencies are allowed for svg or png images.
  - Recommended maximum size for iconURL is 15kb.
expirationDate : Insert the credential expiration date, after which it will not be considered valid and cannot be verified. Expiration date can not be in the past.
issuanceDate : This is an optional field that enables defining when the credential becomes valid. This can be used to issue future-dated credentials. Value must not be in the past or after expirationDate, when the latter is specified. When not specified, issuanceDate will default to the current time.
tag : Insert a tag to reference this credential. The tag gets stored as part of the credential metadata and can be used to search for it in the credential registry. Note that tags are case sensitive.
proofType (optional): This is an optional field used to define the cryptographic algorithm used to sign the credential. The credential Issuer’s DID must contain a key that supports the corresponding signing capability. If no proofType is provided, the credential will be signed using the key that is available in the Issuer’s DID:
- If a Bls12381G2 key is available, the credential will be signed with a BbsSignature2022 proof. Credentials signed with this proof type support selective disclosure.
- If a Bls12381G2 key is unavailable, but a Ed25519 key is available, the credential will be signed with a Ed25519Signature2018 proof. Credentials signed with this proof type do not support selective disclosure.
- If none of the two suitable keys are available, the request will be rejected and the credential will not be issued.
persist : When set to true, both the issued credential and its metadata are stored in the credential registry. When set to false (default) only the following metadata is stored in the credential registry:
- id
- tag
- credentialStatus
- issuanceDate
  ⚠️
  Credentials by nature tend to hold Personally Identifying Information (PII). Before storing credential data, familiarise yourself with compliance to any PII restrictions that may apply to your use-case.
revocable : When set to true (default), the created credential can later be revoked, and https://w3id.org/vc-revocation-list-2020/v1 is injected into the credential @context object when it is issued. This references the JSON-LD definition of the credentialStatus object used to manage revocation status. When set to false, the credential cannot be revoked.
includeId : When set to true, the signed credential identifier is included in both the credential object and the credential metadata. When set to false it is only included in the credential metadata.

Response

JSON

{
    "id": "b955f2f1-2ea7-4225-a74e-4111094074be",
    "tag": "external-identifier",
    "credential": {
        "id": "b955f2f1-2ea7-4225-a74e-4111094074be",
        "type": ["VerifiableCredential", "EducationalOccupationalCredential", "AlumniCredential"],
        "issuer": {
            "id": "did:web:learn.vii.au01.mattr.global",
            "name": "Zealopia Business Institute",
            "logoUrl": "https://static.mattr.global/credential-assets/zealopia/web/icon.svg",
            "iconUrl": "https://static.mattr.global/credential-assets/zealopia/web/logo.svg"
        },
        "name": "Course credential",
        "description": "This credential shows that the person has attended the mention course and attained the relevant awards.",
        "credentialBranding": {
            "backgroundColor": "#6303FF",
            "watermarkImageUrl": "https://static.mattr.global/credential-assets/zealopia/web/watermark.svg"
        },
        "issuanceDate": "2024-01-10T22:54:57.083Z",
        "expirationDate": "2025-02-01T08:12:38.156Z",
        "credentialSubject": {
            "id": "did:key:z6Mkr9f7o82NFLRFTTCWRR1GiZpca22Xf6YKo2zKThrZMA2w",
            "givenName": "Emma",
            "familyName": "Tasma",
            "alumniOf": "Zealopia University"
        },
        "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://w3id.org/vc-revocation-list-2020/v1",
            "https://mattr.global/contexts/vc-extensions/v2"
        ],
        "credentialStatus": {
            "id": "https://learn.vii.au01.mattr.global/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f#1",
            "type": "RevocationList2020Status",
            "revocationListIndex": "1",
            "revocationListCredential": "https://learn.vii.au01.mattr.global/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f"
        },
        "proof": {
            "type": "Ed25519Signature2018",
            "created": "2024-01-10T22:54:57Z",
            "verificationMethod": "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
            "proofPurpose": "assertionMethod",
            "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..NgQKScBviBxYE0M2lCS4x8dDZI-eMPo_bMEXyldYGM5k0uh29c0YbgW6xbvzaaioUjbHr3ZUUlq2E8TcOOA9Bg"
        }
    },
    "credentialStatus": {
        "id": "https://learn.vii.au01.mattr.global/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f#1",
        "type": "RevocationList2020Status",
        "revocationListIndex": "1",
        "revocationListCredential": "https://learn.vii.au01.mattr.global/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f"
    }
}

id : Unique identifier of the new JSON credential.
credential : The credential object contains the following amendments on in addition to the information provided in the request:
- id : If includeId was set to true in the request, the JSON credential unique identifier is included inside the credential object. This would be identical to the top-level id element.
- type : Every W3C verifiable credential must include VerifiableCredential in the type property, so MATTR VII also auto-injects this as the first element.
- issuanceDate : Timestamp indicating when the credential was signed.
- @context : As part of the credential generation MATTR VII will auto-inject the following contexts, which reference the W3C Verifiable Credential definitions:
  - https://www.w3.org/2018/credentials/v1
  - https://mattr.global/contexts/vc-extensions/v2
  - https://w3id.org/vc-revocation-list-2020/v1 (only if revocable was set to true to create a revocable credential).
  If you require introducing a different context for your production implementation, please contact us. Referenced contexts must be whitelisted or credential issuance will fail. In-line context definitions are not supported and would also result in an error.
- credentialStatus : When revocable is set to true in the request, this element includes information that enables future revocation of the credential.
- proof :Includes information regarding the encryption algorithm used to sign the credential and how it can be verified.

Branded credential

The following image depicts how the credential created above would look like once available in the holder’s digital wallet. It might help you better understand how to brand your own credential:

Branding

Refer to this video to learn more about credential branding best practices.
Check out our Silvereye branding tool to get a real time preview of a credential based your settings and configuration.

Encrypt the signed credential

Once the new JSON credential is signed, we need to encrypt it before sharing it with the intended holder as an encrypted message.

Encrypt a credential request

Make a request of the following structure to encrypt your signed JSON credential:

HTTP

POST /v1/messaging/encrypt

Request body

JSON

{
    "senderDidUrl": "did:web:learn.vii.au01.mattr.global#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
    "recipientDidUrls": [
        "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
    ],
    "payload": {
        "id": "b955f2f1-2ea7-4225-a74e-4111094074be",
        "type": "https://mattr.global/schemas/verifiable-credential/offer/Direct",
        "to": [
            "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
        ],
        "from": "did:web:learn.vii.au01.mattr.global",
        "created_time": 1624509675690,
        "body": {
            "credentials": [
                {
                    "id": "b955f2f1-2ea7-4225-a74e-4111094074be",
                    //... rest of credential information
                }
            ],
            "domain": "learn.vii.au01.mattr.global"
        }
    }
}

senderDidUrl : The sender’s DID URL, obtained from the id field of the first keyAgreement entry of the DID document.
recipientDidUrls : Use your Subject DID. This ensures that only that recipient is able to view the message and claim the credential.
payload :
- id : Use the id from the credential generated in the previous step.
- type : Use https://mattr.global/schemas/verifiable-credential/offer/Direct. This informs the wallet how to respond to the message.
- from : Use your Issuer DID.
- to : Use your Subject DID.
- created_time : Use a unix timestamp provided as a number (not a string).
- body :
  - credentials : Use the credential object from the signed credential. Make sure not to include any other elements from the credential.
  - domain : Use your tenant domain.

Encrypted message response

The response body contains a JSON Web Encryption (JWE) object:

JSON

{
    "jwe": {
        "protected": "eyJhbGciOiJYQzIwUCJ9",
        "recipients": [
            {
                "header": {
                    "alg": "ECDH-1PU+A256KW",
                    "kid": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi#z6LSoYqvKWzd8faMroS4WMHRfzeDR22w5nrcGEi9MRV4BEYA",
                    "epk": {
                        "kty": "OKP",
                        "crv": "x25519",
                        "x": "ovKlBgAF969Mpa6XYhV6imLcX4ZyVQQTpU3FkjFKk2Y"
                    },
                    "skid": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx#z6LSkHGWvAejiTJtKte98QAJmeSDaMtJMoupTba471nZRQhc"
                },
                "encrypted_key": "pZwsbPa7Vfq6KrKKLEg1jOFFkBRufsTOjrEZX6fwnu6rpQt8G_O42Q"
            }
        ],
        "ciphertext": "wOiJL0zmZSaSdAk3Wn5m_XzeyiVvpJXRX3FTy0ivr3D3DTibge2I7m6DJ3kaDmXi17sy2cL0r3lsddxBcXEPDfrL8o6y5oIyodcQAo4tMY4IOXdsFHN4cTWjOyrsZhT-1GGb0QYyQ7LgCE7WgYdMX-fBetr8fhVxAoVeyYkBxRhXhF47elWlNqoLT7dfsUVYCPBjY0GN0ciQOzBvcplB8hrqVWaTvdbpgoPIGGKxcXl907gnIAX8rzFcRfh66t6M2SlGZ5pCeDvlne-StPxvIxvGJaQq02tWuA2Yykz5Gw6zz5xmPSrj7yyy26ABSM4yjQcu2q-payWQx1lkGaLrPpsbhKzq5KcXNlviz6r3aw3ERt4OO-NxmBu4ZCeK1Uvfo_wXwTawOpdjF6RB7RRjO5TJ1fGEWjpl1p84T0e-n6CE_Kxibklh4bucmx55F1rgQc1280C0k4DNJlplhoNGlFyOfaYBraT-vOJ0Fv-hKpv41npGf_uCr56Cjb4pKvMEngpAA2dglfMO0NBN5hf_FdoC6g17h4PWxcBnuCDRQcDfHvopCuCfU2H4saL07R-YRcokis2tBii7FZKS7F-eQozHzgYl68ZI3Cd5eo-4VUp3e1Xmd-b53mF3bRutV9JcY7KA1AQnwm2yyTFz0ss7a21KsYZHUi-eIhbaEf88BiMrblvp4ztDPuXUmwG4RowoRd5ZSJsdOHrkm2fniyISLGaPgcSeot22_HHsXf8bqhyxNbr6e4ghTuVZgTBBpv15DT2KSj3z3_2TgeD6VpIFwJQm1Dn_hZnSpFx-h57nsEyAAW5C9XoVJ5usnzn7TQJtZM6wsFFGd1Bgs8Xmf0p79J-QXkAWmhDi6mct5unsEnr52hnzGyLfsoH8YUjffkI55U86JZKrcMycV92IN6jF4cMoe8FbfVyu4pNrh4vKIkgVqJO0B50z0OIk8WEYIV1HoWxIzXiH6VLiC5QEZaCFyVUOnr4PFsNICLEedYwE6w0XmR2fpeMz529RPamJPYlBb9dZMGJ2RL-RnJYIH8BbhxN08EFS-4RXl27PjRoam2W6fR3fbyrObfh4H6JwXXi4ATelcBucE4zZUMrjsXMbW4CrduIis0c0f8eOPeGV4uW4W9lg4-DbsUOYY1frBSv6_1krmEvQQLgu087KfLgWMz7wqNO7UuF96ECIi7Z1yPCwx4vmtKOJN5lbFXZkzTCtV4-bltNr9PzLBJF4krqNJkwEgKe3kzrAnABKJQx1aDATk8gUJUu14635hduGBWPrY3b_isVr9tzflkCMFXq5SXV24YYCAjQsTXIRbJyV5756NwiT2L7FqzgzLmd3X6hZ5LCjv9KJwDEVCWTN9v2Zbmi8WFwrDz5LeokLGA4_Km48aJYMGpxPmL0wkEXynkIX0IhJrEu9uxEKHzEia_WjDIw80VwghZpXGVw3jYDs5R7O-zhv2lcR3UXJr_XMroe7jAV5pqWop_-ek1r7Qpt-rudjS3q_zC-uuG0SkXsL47Ni92e3MPyeDjukWAamMx7HqTx_azNL9JeeZ-w_8qd6x4wKo6qB7R0-WDFsOXHYM8HT5Aw6sKX48Dl0VfZaBE4JBXTVWTs4C9n4p3gu11bRB-tj01c3usw0vx3N-EIs5Y6cXcx3UN0O2ykWF3jCpEecUNCIzNKFTDrjALZXFvzlrdeyW5QO6sGdSVIsAZ4MDlTLRen0rzJkmw0cDmvN0OG6TvVgBoIv-Kc35g-4I8FQuUW-pIS9gQONYmCgXkQfxzjJdrcMCtQ1sV9kcg5CCirQ3KYH-5c3GhriDrNZIGJX3XkERFR9CqPFU6RSocReOr0iAx8LtssuiE1X2OeywQaAop8DJ1aQ3xaQwJQGCWSzKu_49ee6RhqSpq0EyPILxwqoHhP38NKlw5F5KGdWo6FqEzIcFVOOO160mv_yeYnIOIUnQEOGxcWSKVCiJmMcXadxtEWk2jqItbJiDxoOWs4d34eaWebVyoNOhcaim7UZQq0tE-GpFi8SZZmOmnIxL0lgZYYkvWH5WVY-n7Be6c9KoMYvQVFQ69EndcqS0zLV6unV0aZ-3CTXU1CvfSKZ1obsEozE1elYZawKiAUXQEoe2hhSmd63b3QSbduLDPs=",
        "iv": "QKTq99Y9NjnWIDvU1XldP23j5eqXamrf",
        "tag": "TXfEcE1wFMOOjE0GCCI7BA=="
    }
}

Once you have an encrypted message containing the credential in a format that a wallet can make sense of, you need to share it with its intended holder. This can be achieved in one of the following methods:

Share via a DID message
Share via a QR code.
Share via a Deeplink.

The credential is sent directly to the wallet and will not require the user to go to a website or perform any action other than accepting the new credential.

You can use the MATTR VII platform messaging endpoint to send the credential as a message to the holder. If the holder have enabled notifications on their wallet, they will receive a push notification. If they haven’t, they will be alerted the next time they open the app.

Send a message request

Make a request of the following structure to share the encrypted credential as a DID message:

HTTP

POST /v1/messaging/send

Request

JSON

{
  "to": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
  "message": {
        "protected": "eyJhbGciOiJYQzIwUCJ9",
        "recipients": [
            {
                "header": {
                    "alg": "ECDH-1PU+A256KW",
                    "kid": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi#z6LSoYqvKWzd8faMroS4WMHRfzeDR22w5nrcGEi9MRV4BEYA",
                    "epk": {
                        "kty": "OKP",
                        "crv": "x25519",
                        "x": "ovKlBgAF969Mpa6XYhV6imLcX4ZyVQQTpU3FkjFKk2Y"
                    },
                    "skid": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx#z6LSkHGWvAejiTJtKte98QAJmeSDaMtJMoupTba471nZRQhc"
                },
                "encrypted_key": "pZwsbPa7Vfq6KrKKLEg1jOFFkBRufsTOjrEZX6fwnu6rpQt8G_O42Q"
            }
        ],
        "ciphertext": "wOiJL0zmZSaSdAk3Wn5m_XzeyiVvpJXRX3FTy0ivr3D3DTibge2I7m6DJ3kaDmXi17sy2cL0r3lsddxBcXEPDfrL8o6y5oIyodcQAo4tMY4IOXdsFHN4cTWjOyrsZhT-1GGb0QYyQ7LgCE7WgYdMX-fBetr8fhVxAoVeyYkBxRhXhF47elWlNqoLT7dfsUVYCPBjY0GN0ciQOzBvcplB8hrqVWaTvdbpgoPIGGKxcXl907gnIAX8rzFcRfh66t6M2SlGZ5pCeDvlne-StPxvIxvGJaQq02tWuA2Yykz5Gw6zz5xmPSrj7yyy26ABSM4yjQcu2q-payWQx1lkGaLrPpsbhKzq5KcXNlviz6r3aw3ERt4OO-NxmBu4ZCeK1Uvfo_wXwTawOpdjF6RB7RRjO5TJ1fGEWjpl1p84T0e-n6CE_Kxibklh4bucmx55F1rgQc1280C0k4DNJlplhoNGlFyOfaYBraT-vOJ0Fv-hKpv41npGf_uCr56Cjb4pKvMEngpAA2dglfMO0NBN5hf_FdoC6g17h4PWxcBnuCDRQcDfHvopCuCfU2H4saL07R-YRcokis2tBii7FZKS7F-eQozHzgYl68ZI3Cd5eo-4VUp3e1Xmd-b53mF3bRutV9JcY7KA1AQnwm2yyTFz0ss7a21KsYZHUi-eIhbaEf88BiMrblvp4ztDPuXUmwG4RowoRd5ZSJsdOHrkm2fniyISLGaPgcSeot22_HHsXf8bqhyxNbr6e4ghTuVZgTBBpv15DT2KSj3z3_2TgeD6VpIFwJQm1Dn_hZnSpFx-h57nsEyAAW5C9XoVJ5usnzn7TQJtZM6wsFFGd1Bgs8Xmf0p79J-QXkAWmhDi6mct5unsEnr52hnzGyLfsoH8YUjffkI55U86JZKrcMycV92IN6jF4cMoe8FbfVyu4pNrh4vKIkgVqJO0B50z0OIk8WEYIV1HoWxIzXiH6VLiC5QEZaCFyVUOnr4PFsNICLEedYwE6w0XmR2fpeMz529RPamJPYlBb9dZMGJ2RL-RnJYIH8BbhxN08EFS-4RXl27PjRoam2W6fR3fbyrObfh4H6JwXXi4ATelcBucE4zZUMrjsXMbW4CrduIis0c0f8eOPeGV4uW4W9lg4-DbsUOYY1frBSv6_1krmEvQQLgu087KfLgWMz7wqNO7UuF96ECIi7Z1yPCwx4vmtKOJN5lbFXZkzTCtV4-bltNr9PzLBJF4krqNJkwEgKe3kzrAnABKJQx1aDATk8gUJUu14635hduGBWPrY3b_isVr9tzflkCMFXq5SXV24YYCAjQsTXIRbJyV5756NwiT2L7FqzgzLmd3X6hZ5LCjv9KJwDEVCWTN9v2Zbmi8WFwrDz5LeokLGA4_Km48aJYMGpxPmL0wkEXynkIX0IhJrEu9uxEKHzEia_WjDIw80VwghZpXGVw3jYDs5R7O-zhv2lcR3UXJr_XMroe7jAV5pqWop_-ek1r7Qpt-rudjS3q_zC-uuG0SkXsL47Ni92e3MPyeDjukWAamMx7HqTx_azNL9JeeZ-w_8qd6x4wKo6qB7R0-WDFsOXHYM8HT5Aw6sKX48Dl0VfZaBE4JBXTVWTs4C9n4p3gu11bRB-tj01c3usw0vx3N-EIs5Y6cXcx3UN0O2ykWF3jCpEecUNCIzNKFTDrjALZXFvzlrdeyW5QO6sGdSVIsAZ4MDlTLRen0rzJkmw0cDmvN0OG6TvVgBoIv-Kc35g-4I8FQuUW-pIS9gQONYmCgXkQfxzjJdrcMCtQ1sV9kcg5CCirQ3KYH-5c3GhriDrNZIGJX3XkERFR9CqPFU6RSocReOr0iAx8LtssuiE1X2OeywQaAop8DJ1aQ3xaQwJQGCWSzKu_49ee6RhqSpq0EyPILxwqoHhP38NKlw5F5KGdWo6FqEzIcFVOOO160mv_yeYnIOIUnQEOGxcWSKVCiJmMcXadxtEWk2jqItbJiDxoOWs4d34eaWebVyoNOhcaim7UZQq0tE-GpFi8SZZmOmnIxL0lgZYYkvWH5WVY-n7Be6c9KoMYvQVFQ69EndcqS0zLV6unV0aZ-3CTXU1CvfSKZ1obsEozE1elYZawKiAUXQEoe2hhSmd63b3QSbduLDPs=",
        "iv": "QKTq99Y9NjnWIDvU1XldP23j5eqXamrf",
        "tag": "TXfEcE1wFMOOjE0GCCI7BA=="
    }
}

to : Use the Subject DID.
message : Use the jwe object from the encrypted message.

Response

A 200 response indicates that the message payload was sent to the service endpoint of the dereferenced DID Document (or the default MATTR service endpoint).

On the holder’s mobile device, they should see a notification message appear. Tapping on the message would require authenticating using their device configured authentication method. The app should then navigate to the credential offer screen, where they can view and accept the credential.

You can redirect the holder’s MATTR Wallet to claim the encrpyted credential by scanning a QR code, as the wallet will follow valid 302 redirects to online resources. To achieve this you will need to:

Host the encrypted credential as an available web resource.
Create a URL that would enable the wallet to claim the credential.
Embed this URL into a QR code.
Share the QR code with the holder.

Perform the following steps to share the encrpyted credential as a QR code:

Encode the jwe object from the encrypted message into base64url to make it URL safe. You can use an online tool such as this one - make sure you toggle URL safe.
Create a redirect on your host that will serve the encrypted credential:

Redirect	Content
redirectid=1234567	request=ewogI… // base64url encoded encrypted credential

Construct a URL of the following structure:

HTTP

didcomm://https://learn.mattr.global?redirectid=1234567

https://learn.mattr.global : Replace with the URL of the host that will serve the encrypted credential.
1234567 : Replace with the created redirect identifier.

Convert the URL from step 3 to a QR code using any QR encoder such as QR Code Generator or QR Server.
Share the generated QR code with the holder using your preferred communication channel (e.g. e-mail, messaging apps, printed copy, etc.).

When the holder opens the MATTR Showcase Wallet and scans the QR code, the wallet will follow the configured redirect to the credential offer screen, where the holder can view and accept the credential.

You can redirect the holder’s MATTR Wallet to claim the encrpyted credential by following a deeplink, as the wallet will follow valid 302 redirects to online resources. To achieve this you will need to:

Host the encrypted credential as an available web resource.
Create a URL that would enable the wallet to claim the credential.
Embed this URL into a deeplink.
Share the deeplink with the holder.

Perform the following steps to use a deeplink to share the encrpyted credential:

Encode the jwe object from the encrypted message into base64url to make it URL safe. You can use an online tool such as this one - make sure you toggle URL safe.
Create a redirect on your host that will serve the encrypted credential:

Redirect	Content
redirectid=1234567	request=ewogI… // base64url encoded encrypted credential

Construct a URL of the following structure:

HTTP

didcomm://https://learn.mattr.global?redirectid=1234567

https://learn.mattr.global : Replace with the URL of the host that will serve the encrypted credential.
1234567 : Replace with the created redirect identifier.

Encode the URL from step 3 into base64url. You can use the same tool you used in step 1.
Finally, combine the encoded URL from step 4 with the MATTR Showcase Wallet bundle id (global.mattr.wallet) to create a wallet deeplink:

HTTP

global.mattr.wallet://accept/ZGlkY29tbTovL2h0dHBzOi8vWU9VUl9IT1NUX1BST1ZJREVSLmNvbT9yZWRpcmVjdGlkPTEyMzQ1Njc

Share the generated deeplink with the holder using your preferred digital communication channel (e.g. e-mail, messaging apps, etc.).

When the holder uses their mobile device to follow the deep link, the MATTR Showcase wallet will be launched and follow the configured redirect to the credential offer screen, where the holder can view and accept the credential.

MATTR is not affiliated with any of the service providers mentioned in this guide and cannot vouch for their offerings.

Google Digital Pass OID4VCI

How to issue a JSON credential (Direct issuance)

Prerequisites

Overview

Sign the JSON credential

Request

Request body

Response

Branded credential

Encrypt the signed credential

Encrypt a credential request

Request body

Encrypted message response

Share the encrypted credential

Send a message request

Request

Response