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

Overview

Sending a status change notification comprises the following steps:

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

Create a revocation message payload

Request

Make a request of the following structure to create a revocation message:

HTTP


POST /v2/credentials/web-semantic/{id}/revocation-status/notification

id : Provide the id for the credential whose status has changed.

Request body

JSON


{
    "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.

JSON


{
    "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:

HTTP


POST /v1/messaging/encrypt

Request body

JSON


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

JSON


{
    "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:

HTTP


POST /v1/messaging/send

Request body

JSON


{
    "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 the jwe object from the previous step’s response (do not include the jwe 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).