GuidesCredential revocationStatus change notification

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

  1. Create a revocation message payload.
  2. Encrypt the message.
  3. 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"]
}

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

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