Send a message

Introduction

Sending an action-based message to a holder DID associated to a MATTR Wallet first requires a message constructed in a JWM format. Messages are then required to be encrypted for the recipient to ensure privacy.

As a first principle, any JWM based message sent via MATTR VII /messaging/send endpoint is required to be encrypted, thus ensuring messages held at rest cannot be inspected by MATTR or any party (such as a legal enforcing entity) that requests access to those messages.

Prerequisites

You need access to the MATTR VII APIs, If you’re experiencing any difficulties, contact us.

In order to send a message, you will require the subject DID of the recipient, one way of capturing these is to use the DID Auth approach

Construct the JWM Payload

Depending on the type of message to send to the recipient, distinct operations are available:

1. Offer a credential using OpenID Credential Provisioning

Start a credential offer flow by sending a notification message to a known subject DID, the most likely scenario is to reinstate a previously issued credential or to offer a new type of credential to a subject where there is an existing relationship.

Using the Create an OpenId credential offer payload, provide a known DID from the tenant and the subject DID of the intended recipient.

Request

json
Copy to clipboard.
1{
2    "from": "did:web:organization.com",
3    "to": [
4        "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
5    ]
6}

Response

json
Copy to clipboard.
1{
2    "id": "733d1de2-9286-447e-a701-29b1292089d0",
3    "type": "https://mattr.global/schemas/verifiable-credential/offer/OidcCredentialProvider",
4    "to": [
5        "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
6    ],
7    "from": "did:web:organization.com",
8    "created_time": 1616052936783,
9    "body": {
10        "uri": "openid://discovery?issuer=https://YOUR_TENANT_URL/ext/oidc/v1/issuers/58ab2731-16a3-4c4c-a3b2-89fd242d1685"
11    }
12}

The result is a message payload constructed using the JWM format. The body of the message indicates that the message points to an OIDC Credential Issuer, which a digital wallet can consume and start the flow in the wallet.

Note the to and from fields at this level conform with the JWM format but do not necessarily map to the intended credential issuer flow

In order to send this message payload, continue to the Encrypt payload step.

2. Notify of a revocation status change

Whenever a revocation status is updated for a known subject bound credential, a message may be sent to inform the holder of the change in status i.e from active > revoked status or from revoked > active status.

Using the Create a revocation message payload endpoint, provide a known DID from the tenant and the subject DID of the intended recipient.

Request

json
Copy to clipboard.
1{
2    "from": "did:web:organization.com",
3    "to": [
4        "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
5    ]
6}

Response

json
Copy to clipboard.
1{
2    "id": "8acd6b31-9225-47a9-8514-896602f3ac08",
3    "type": "https://mattr.global/schemas/verifiable-credential/status/RevocationStatus",
4    "to": [
5        "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
6    ],
7    "from": "did:web:organization.com",
8    "created_time": 1616137875353,
9    "body": {
10        "revocationListCredential": "https://YOUR_TENANT_URL/v1/revocation-lists/341db0e7-aeb5-4d88-bee2-41be51795266",
11        "revocationListIndex": "1547",
12        "isRevoked": false
13    }
14}

The result is a message payload constructed using the JWM format. The body of the message indicates that the message concerns the status of a given credential which a digital wallet can consume to relay to the holder.

In order to send this message payload, continue to the Encrypt payload step.

3. Start a verification using a callback

Initiating a “Verify Credential” flow follows a standard pattern, however conveying the presentation request to a holder can take various forms. Sending a “Verification Request Notification” fits well when the subject is known and requires further authorization, such as a call center operator using a connected system to request details from a holder whilst on a call.

First understanding the Verify using a callback URL is critical in orchestrating the steps required. In that tutorial, the section to send the Presentation Request via notification covers the general steps to notify subject holders using a digital wallet.

In order to send this message payload, continue to the Encrypt payload step.

4. Send a credential directly

Send a credential that has been created using the Create credential endpoint through to a digital wallet for the holder to then choose to accept.

In order to send this message payload, continue to the Offer a credential tutorial.

General steps

Once the message payload has been created the following steps are required to conform to the message standards applied by the platform.

Encrypt the payload

All messages sent via the platform require the message payload to be encrypted, this is to keep the total privacy of end-users in-mind. End-to-end encryption is a default level privacy that we uphold on the MATTR VII platform.

Use the Encrypt a message to take the message payload and encrypt it for the intended recipient.

First find a key suitable for keyAgreement from the same DIDs used in the message payload by using the Resolve a DID endpoint. Whenever a specific key from a DID document is referenced this is known as a DIDUrl.

Apply the DIDUrl used in the payload for the encryption fields:

  • to > senderDidUrl - generally use the Issuer or Verifier DID and find the keyAgreement key id

  • from > recipientDidUrls - this will be the Subject DID in order to simplify the encryption a simple DID can be included here

Further details on determining which key to use for this encryption can be found on the Encrypt a message

Request

json
Copy to clipboard.
1{
2    "senderDidUrl": "did:web:organization.com#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
3    "recipientDidUrls": [
4        "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
5    ],
6    "payload": {}
7}

Response

json
Copy to clipboard.
1{
2    "jwe": {
3        "protected": "eyJhbGciOiJYQzIwUCJ9",
4        "recipients": [
5            {
6                "header": {
7                    "alg": "ECDH-1PU+A256KW",
8                    "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
9                    "epk": {
10                        "kty": "OKP",
11                        "crv": "x25519",
12                        "x": "-9bAWdOMBsvfM3ub1lhpBk-q07WVH1QAzg7j0_4cxFA"
13                    },
14                    "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
15                },
16                "encryption_key": "m7bC06RzCo2Wx3uFKqQM2ocf4Bio32Gh9NSLAkHTDD-jEC2G0ha0GQ"
17            }
18        ],
19        "ciphertext": "GuO_bBFQmhRI7Ayo4-0=",
20        "iv": "TeV-Nk3g_lcCfOQsJu0Qw2tZnK_cZyeH",
21        "tag": "c51lspb_41lEDTq6El8vIw=="
22    }
23}

Send the message

Use the Send message endpoint to send the encrypted payload message to the service endpoint of a DID.

The DID specified in the to field is used to lookup the service endpoint from the DID Document. Given the DID is a did:key method the default MATTR service endpoint is used.

Request

json
Copy to clipboard.
1{
2    "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
3    "message": {
4        "protected": "eyJhbGciOiJYQzIwUCJ9",
5        "recipients": [
6            {
7                "header": {
8                    "alg": "ECDH-1PU+A256KW",
9                    "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
10                    "epk": {
11                        "kty": "OKP",
12                        "crv": "x25519",
13                        "x": "-lCJVzF1BPwk68QuFu7HWY8zUe_KZJD7FKGZRcZkeWI"
14                    },
15                    "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
16                },
17                "encryption_key": "ou2o8IWddajOu_dXkL9pRxnyBbTH1QkbIb54QgjhGWiBI9NelriRyA"
18            }
19        ],
20        "ciphertext": "e-Dzplvt23o9oM6Ytht0Y3guq-DNfnHx54LI7N281scoHpGTUZ14Yk_djgdrB3sctRjf6mPRuH9542Cc2j5H4VC0Dyd1rLBWcOWuqd5SmP9baLIc8CEkylHht6NZQxd9adZ88rXsCs8FMi_v-xgxx73WfOYULbmuj10vkkcE8U4VDA24WAAOiPaGlUUFbHnsoPwQhO96YYFFtTjSc7n8cMm1s_1sAmRZTa8vQSopHBjpP4CRwtvmemXGunKncIrt6QeVgWNmfuUEXLvFj4Lg9k840gaj5AlfEqGXuT56nYJc5kz2iLjE0dUJ7vusNtRSVkyY47nymMf0ZLSNcZvIwmEXJguLFDk83oPekvQVMWL0bGe4C0K_S8CXwdwHtBQm5KMkjn3iCsalAP_wyECmjFB4P-p0ZSEczTT2QuHlcyI4WuF-5X_Biq6Pa2uDtkiPDdgbbarxyY21RQMlB59SkwKpVRM8x30MJf28nQsFBLdcci9AqrBTxhHPFeOCx8Yy3o8N_J5fL_uFCmXKM42IGY_GNj9a1nGwilcvjftnRZE4RH1hvNyFWL3kwpUbgfEHfWXB8IGJyDA=",
21        "iv": "HgRemJuV7pBgo-aaXdM9Op7lbjR5wPDV",
22        "tag": "7AK7MMSplFzJbyItTP5C-Q=="
23    }
24}

Response

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

Note: It’s generally intended that the DID and associated DIDUrl used in the to field of the payload (required for JWM), matches the recipientDidUrls (encrypts the message) and the to field of the Send message endpoint (defines the service endpoint) are all related. Using distinct DIDs could result in messages not being sent or interpreted incorrectly by the wallet.

Try it out

Make sure you have the MATTR Wallet app installed and have accepted the notification request during the onboarding steps.

  1. First, obtain a DID from the mobile wallet using DID Auth

  2. Create a Credential offer message payload

  3. Encrypt the payload

  4. Send the encrypted payload

On your mobile device, you should see a notification message appear. Tap on the message and authenticate using biometrics or PIN. The app should navigate you to the credential offer screen where you can begin the obtaining a credential journey.