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.
A DID of the recipient intended for the message
Setup of an OpenID or OIDC Credential Issuer
Understanding of revocation status updates
Able to verify a credential using a callback url
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
1{
2 "from": "did:web:organization.com",
3 "to": [
4 "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
5 ]
6}
Response
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
andfrom
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
1{
2 "from": "did:web:organization.com",
3 "to": [
4 "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
5 ]
6}
Response
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 idfrom
>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
1{
2 "senderDidUrl": "did:web:organization.com#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
3 "recipientDidUrls": [
4 "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
5 ],
6 "payload": {}
7}
Response
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 adid:key
method the default MATTR service endpoint is used.
Request
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
A 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 therecipientDidUrls
(encrypts the message) and theto
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.
First, obtain a DID from the mobile wallet using DID Auth
Create a Credential offer message payload
Encrypt the payload
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.