Revocation status change notification

Whenever a revocation status is updated for a known subject-bound credential, a message can be sent to inform the holder of the status change. This comprises three steps:

Create a revocation message payload.
Encrypt the message payload.
Send the encrypted message.

Create a revocation message payload

Make the following request to create a revocation message payload:

Request

httpCopy to clipboard.
POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/{id}/revocation-status/notification

id: Provide the identifier for the credential whose status has changed. This identifier can be retrieved using the relevant MATTR VII APIs.

jsonCopy to clipboard.
{
    "from": "did:web:organization.com",
    "to": [
        "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
    ]
}

from: 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.
to: The recipient DID URL. 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.

Response

jsonCopy to clipboard.
{
    "id": "8acd6b31-9225-47a9-8514-896602f3ac08",
    "type": "https://mattr.global/schemas/verifiable-credential/status/RevocationStatus",
    "to": [
        "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
    ],
    "from": "did:web:organization.com",
    "created_time": 1616137875353,
    "body": {
        "revocationListCredential": "https://YOUR_TENANT_URL/v1/revocation-lists/341db0e7-aeb5-4d88-bee2-41be51795266",
        "revocationListIndex": "1547",
        "isRevoked": false
    }
}

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.

Encrypt the message payload

Once you have the message payload, make the following request to encrypt it:

Request

httpCopy to clipboard.
POST https://YOUR_TENANT_URL/v1/messaging/encrypt

jsonCopy to clipboard.
{
    "senderDidUrl": "did:web:organization.com#CU6dJt9p8t",
    "recipientDidUrls": [
      "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
    ],
    "payload": {
      "id": "8acd6b31-9225-47a9-8514-896602f3ac08",
      "type": "https://mattr.global/schemas/verifiable-credential/status/RevocationStatus",
      "to": [
          "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
      ],
      "from": "did:web:organization.com",
      "created_time": 1616137875353,
      "body": {
          "revocationListCredential": "https://YOUR_TENANT_URL/v1/revocation-lists/341db0e7-aeb5-4d88-bee2-41be51795266",
          "revocationListIndex": "1547",
          "isRevoked": false
      }
    }
}

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: The recipient's DID URL. In production environments, you must have a secure way to obtain the DID that is associated with the intended recipient's digital wallet:
- Use DID Auth for a new interaction.
- Ask the user to manually obtain their public DID by opening their MATTR Showcase wallet and navigating to Settings > Advanced > Public DID.
- Request an existing credential as part of a verification workflow, and extract the recipient's digital wallet DID from that interaction.
payload: Use the body of the JWM payload obtained in the previous step.

Response

jsonCopy to clipboard.
{
  "jwe": {
    "protected": "eyJhbGciOiJYQzIwUCJ9",
    "recipients": [
      {
        "header": {
          "alg": "ECDH-1PU+A256KW",
          "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
          "epk": {
            "kty": "OKP",
            "crv": "X25519",
            "x": "JOLnYaD7L-Rszz7fczPhn6MkNre25PUsztzB1RHoz14"
          },
          "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
        },
        "encryption_key": "ag5iKzjJOth9Wa68dCVKJW_vnO_Ga0zSJgQp5rIUg69HCzIjuNYhDg"
      }
    ],
    "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
    "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
    "tag": "u8kT0VAAtTswjGXxNpuX0g=="
  }
}

The result is a message payload constructed using the JWM format which can be used as a secure MATTR VII message.

Send the encrypted message

Make the following request to send the notification to the user's digital wallet:

Request

httpCopy to clipboard.
POST https://YOUR_TENANT_URL/v1/messaging/send

jsonCopy to clipboard.
{
﻿"to"﻿:﻿ ﻿"{SUBJECT_DID}"﻿,﻿
﻿﻿"message"﻿:﻿ ﻿{
  "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
  "message": {
    "protected": "eyJhbGciOiJYQzIwUCJ9",
    "recipients": [
      {
        "header": {
          "alg": "ECDH-1PU+A256KW",
          "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
          "epk": {
            "kty": "OKP",
            "crv": "X25519",
            "x": "JOLnYaD7L-Rszz7fczPhn6MkNre25PUsztzB1RHoz14"
          },
          "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
        },
        "encryption_key": "ag5iKzjJOth9Wa68dCVKJW_vnO_Ga0zSJgQp5rIUg69HCzIjuNYhDg"
      }
    ],
    "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
    "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
    "tag": "u8kT0VAAtTswjGXxNpuX0g=="
    }
  }
}

to: Use your recipient's wallet public DID. This can be obtained from previous interactions, via DID authentication or directly from the user's wallet.
message: Use the content of the jwe object obtained in the previous step response. Note that you do not need to include the preceding jwe attribute, only the content of the object.

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).

^PrevCredential registry