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 Sovrin message.

Prerequisites

• Access to Sovrin 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 Sovrin creates did:web 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 (Sovrin Showcase wallet or Sovrin 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.

• Optional: We have created a curated collection of APIs dedicated to our Sovrin platform, which can make it easier for you to complete this tutorial. Try it out by following this guide.

Request

Make the following request to encrypt your message:

POST https://api.sovrin.one/v1/messaging/encrypt

{
    "senderDidUrl": "did:web:organization.com#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
    "recipientDidUrls": [
        "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
    ],
    "payload": {
        "id": "c80cf529-1449-42b0-a972-ee975720859d",
        "type": "https://sovrin.one/schemas/verifiable-credential/offer/Direct",
        "to": [
            "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
        ],
        "from": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
        "created_time": 1624509675690,
        "body": {
            "credentials": [
                {
                    "@context": [
                        "https://www.w3.org/2018/credentials/v1",
                        "https://schema.org"
                    ],
                    "type": [
                        "VerifiableCredential",
                        "CourseCredential"
                    ],
                    "issuer": {
                        "id": "did:web:organization.com",
                        "name": "tenant"
                    },
                    "issuanceDate": "2021-07-26T01:05:05.152Z",
                    "credentialSubject": {
                        "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
                        "givenName": "Chris",
                        "familyName": "Shin",
                        "educationalCredentialAwarded": "Certificate Name"
                    },
                    "proof": {
                        "type": "Ed25519Signature2018",
                        "created": "2021-07-26T01:05:06Z",
                        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..o6hnrrWpArG8LQz2Ex_u66_BtuPdp3Hkz18nhNdNhJ7J1k_2lmCCwsNdmo-kNFirZdSIMzqO-V3wEjMDphVEAA",
                        "proofPurpose": "assertionMethod",
                        "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
                    }
                }
            ],
            "domain": "api.sovrin.one"
        }
    }
}

• 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://sovrin.one/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 subdomain.

Response

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

{
    "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=="
    }
}

What's Next?

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