How to send a status change notification
Whenever a revocation status is updated for a known subject-bound credential (CWT and JSON credentials), a message can be sent to inform the holder of the status change.
Status change notification is not currently available for mDocs.
Prerequisites
- The
id
of the credential whose status has changed. It can be obtained from the response when you created the credential. - 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.
- Refer to Create a
- Subject DID: This is a
did:key
that identifies the credential holder. It is usually retrieved from the 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 the holder’s digital
wallet DID:
- Use DID Auth for any new interactions.
- Ask the user to share their wallet DID.
- Request an existing credential as part of a verification workflow, and extract the DID from that interaction.
- Refer to
- Issuer DID: This is a
Overview
Sending a status change notification comprises the following steps:
Create a revocation message payload
Request
Make a request of the following structure to create a revocation message:
POST /v2/credentials/web-semantic/{id}/revocation-status/notification
id
: Provide theid
for the credential whose status has changed.
Request body
{
"from": "did:web:organization.com",
"to": ["did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"]
}
from
: Use the Issuer DID.to
: Use the Subject DID.
Response
The response 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 and relay to the holder.
{
"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": "/v1/revocation-lists/341db0e7-aeb5-4d88-bee2-41be51795266",
"revocationListIndex": "1547",
"isRevoked": false
}
}
id
: Unique identifier of the credential whose status has changed.type
: Indicates that this is a status notification message.created_time
: Message timestamp.body
: Details regarding the credential revocation status.
Encrypt the message
Request
Make a request of the following structure to encrypt the message:
POST /v1/messaging/encrypt
Request body
{
"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": "/v1/revocation-lists/341db0e7-aeb5-4d88-bee2-41be51795266",
"revocationListIndex": "1547",
"isRevoked": false
}
}
}
senderDidUrl
: Use the Issuer DID.recipientDidUrls
: Use the Subject DID.payload
: Use the JWM payload obtained in the response in the previous step.
Response
{
"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=="
}
}
Send the message
Request
Make a request of the following structure to send the encrypted message to the holder’s digital wallet:
POST /v1/messaging/send
Request body
{
"to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
"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 the Subject DID.message
: Use the content of thejwe
object from the previous step’s response (do not include thejwe
property name, just its content).
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).