Learn

Encrypt a credential

Now that you have created your credential, you need to encrypt it so that you can send it to a holder's digital wallet as a MATTR VII message.

Prerequisites

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

  • 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 Web Credentials using DIDs with a ed25519 or bls12381g2 key type. Note that 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 is usually retrieved from the intended holder's digital wallet. Refer to create a did:key if you need assistance in creating one for testing this feature. In production environments you must have a secure way to obtain it:

      • Use DID Auth for any new interactions.

      • Ask the user to share their wallet DID (MATTR Showcase wallet or MATTR GO users can do this by navigating to Settings > Advanced > Public DID).

      • Request an existing credential as part of a verification workflow, and extract the DID from that interaction.

  • You must be able to authenticate the user separately from the issuance flow, for example logging into a session on a website/portal or in a physical setting.

Request

Make the following request to encrypt your message:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v1/messaging/encrypt
json
Copy to clipboard.
1{
2    "senderDidUrl": "did:web:learn.vii.au01.mattr.global#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
3    "recipientDidUrls": [
4        "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
5    ],
6    "payload": {
7        "id": "c80cf529-1449-42b0-a972-ee975720859d",
8        "type": "https://mattr.global/schemas/verifiable-credential/offer/Direct",
9        "to": [
10            "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
11        ],
12        "from": "did:web:learn.vii.au01.mattr.global",
13        "created_time": 1624509675690,
14        "body": {
15            "credentials": [
16                {
17                    "@context": [
18                        "https://www.w3.org/2018/credentials/v1",
19                        "https://schema.org"
20                    ],
21                    "type": [
22                        "VerifiableCredential",
23                        "CourseCredential"
24                    ],
25                    "issuer": {
26                        "id": "did:web:organization.com",
27                        "name": "tenant"
28                    },
29                    "issuanceDate": "2021-07-26T01:05:05.152Z",
30                    "credentialSubject": {
31                        "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
32                        "givenName": "Chris",
33                        "familyName": "Shin",
34                        "educationalCredentialAwarded": "Certificate Name"
35                    },
36                    "proof": {
37                        "type": "Ed25519Signature2018",
38                        "created": "2021-07-26T01:05:06Z",
39                        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..o6hnrrWpArG8LQz2Ex_u66_BtuPdp3Hkz18nhNdNhJ7J1k_2lmCCwsNdmo-kNFirZdSIMzqO-V3wEjMDphVEAA",
40                        "proofPurpose": "assertionMethod",
41                        "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
42                    }
43                }
44            ],
45            "domain": "learn.vii.au01.mattr.global"
46        }
47    }
48}

  • senderDidUrl: The sender's DID URL, obtained from the id field of the first keyAgreement entry of the DID document. Refer to our DID tutorial for more information.

  • recipientDidUrls: Use your Subject DID. This ensure 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. 

  • payload.type: Use "https://mattr.global/schemas/verifiable-credential/offer/Direct" . This informs the wallet how to respond to the message.

  • payload.from: Use your Issuer DID.

  • payload.to: Use your Subject DID.

  • payload.created_time: Use a unix timestamp provided as a number (not a string).

  • payload.body.credentials: Use the {credential} object from the credential generated in the previous step. Make sure not to include any other elements from the credential.

  • payload.body.domain: Use your tenant domain.

Response

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

json
Copy to clipboard.
1{
2    "jwe": {
3        "protected": "eyJhbGciOiJYQzIwUCJ9",
4        "recipients": [
5            {
6                "header": {
7                    "alg": "ECDH-1PU+A256KW",
8                    "kid": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi#z6LSoYqvKWzd8faMroS4WMHRfzeDR22w5nrcGEi9MRV4BEYA",
9                    "epk": {
10                        "kty": "OKP",
11                        "crv": "x25519",
12                        "x": "ovKlBgAF969Mpa6XYhV6imLcX4ZyVQQTpU3FkjFKk2Y"
13                    },
14                    "skid": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx#z6LSkHGWvAejiTJtKte98QAJmeSDaMtJMoupTba471nZRQhc"
15                },
16                "encrypted_key": "pZwsbPa7Vfq6KrKKLEg1jOFFkBRufsTOjrEZX6fwnu6rpQt8G_O42Q"
17            }
18        ],
19        "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=",
20        "iv": "QKTq99Y9NjnWIDvU1XldP23j5eqXamrf",
21        "tag": "TXfEcE1wFMOOjE0GCCI7BA=="
22    }
23}

What's Next?

You can now proceed to send the encrypted JWE object to the intended holder's digital wallet.