Learn

Messaging

Sign a message

Accepts a message payload and signs it with a JWS (JSON Web Signature) using the a specific key from the DID (Decentralized Identifier) provided in the request.

Analytic events

  • MESSAGING_SIGN_START
  • MESSAGING_SIGN_SUCCESS
  • MESSAGING_SIGN_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

Sign message request

didUrl
required
string

The did key that will be used to sign the message, which must supports signing. You can obtain it from the DID document DID.localMetadata.initialDidDocument.authentication[0] path.

payload
required
object (JSONObjectMessage)

A JSON Object plaintext message

Responses
200

Message signed

400

Error signing message

post/core/v1/messaging/sign
Request samples
application/json
{
  • "didUrl": "did:web:organization.com#2vcj3MjR4d",
  • "payload": {
    }
}
Response samples
application/json
"eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa21mazNtMldIQlVxVm94SlZ3R1NQejVrYmFKNnpBMXRwN1JRWUJiUUdtczNoI3o2TWttZmszbTJXSEJVcVZveEpWd0dTUHo1a2JhSjZ6QTF0cDdSUVlCYlFHbXMzaCJ9.eyJtc2ciOiJUaGlzIGlzIGEgcGF5bG9hZCJ9.5E9qEmmSOMHLABAr4A9VzuNKFaO4EDo2GSCMoxQm9zsE7eCmEEuaAxtNhOUdd-Wvj64vqBBVl84XB1Yg7X9wBg"

Verify a message

Verifies the siganture of a provided JWS (JSON Web Signature), validating that the payload has not been tampered with and verifying that the kid in the JWS header is the same as the iss value in the Request Object.

One use case for verifying a JWS with a DID is when the Mobile Wallet App sends a Request Object to an OpenID Provider as part of the Authorization Code Flow (as per https://openid.net/specs/openid-connect-core-1_0-final.html#RequestObject). The Request Object is wrapped in a JWS with a signature that is generated from the Subject DID on the mobile app. Therefore verifying the JWS proves that the mobile app has access to the private key of the Subject DID.

Analytic events

  • MESSAGING_VERIFY_START
  • MESSAGING_VERIFY_SUCCESS
  • MESSAGING_VERIFY_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

Provide the JWS to verify

jws
string

JWS (JSON Web Siganture) in its compact form.

Responses
200

Verification successful

400

Invalid JWS

post/core/v1/messaging/verify
Request samples
application/json
{
  • "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Response samples
application/json
{
  • "payload": "payload",
  • "didUrl": "did:web:organization.com#2vcj3MjR4d",
  • "did": "did:web:organization.com",
  • "verified": true,
  • "signerPublicJwk": {
    }
}

Encrypt a message

Encrypts the provided payload using into a JWM (JSON Web Message) format.

Analytic events

  • MESSAGING_ENCRYPT_START
  • MESSAGING_ENCRYPT_SUCCESS
  • MESSAGING_ENCRYPT_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

Encryption parameters

senderDidUrl
required
string

The sender's DID URL, obtained from the id field of the first keyAgreement entry of its DID document (DID.localMetadata.initialDidDocument.keyAgreement[0].id). This must reference a key that supports key agreement.

recipientDidUrls
required
Array of strings

The intended recepient's Subject DID.

payload
required
object

The message to be encrypted.

Responses
200

Message encrypted

400

Bad Request

post/core/v1/messaging/encrypt
Request samples
application/json
{
  • "senderDidUrl": "did:web:learn.vii.au01.mattr.global#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
  • "recipientDidUrls": [
    ],
  • "payload": {}
}
Response samples
application/json
{
  • "jwe": {
    }
}

Decrypt a message

Decrypts a provided message where the tenant manages the keys for the defined recipientDidUrl.

Analytic events

  • MESSAGING_DECRYPT_START
  • MESSAGING_DECRYPT_SUCCESS
  • MESSAGING_DECRYPT_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

Decryption parameters

required
string or EncryptedMessage (object)

The jwe object to be decrypted. It can be extracted from the jwe attribute of the response body you get when encrypting a message. Alternatively, you can use a jwe string using Base64 encoding method and following the JWE open-standard: BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || ASE64URL(JWE Authentication Tag)

Responses
200

Message Decrypted

400

Bad Request

post/core/v1/messaging/decrypt
Request samples
application/json
{
  • "jwe": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDp3ZWI6bWF0dHIuZ2xvYmFsI0V5MkN2V2N5MzQifQ.eyJtZXNzYWdlIjoidGVzdCJ9.dMvOGkfbRrjUJL7XYYAp1UxoHlt8J0N5_vRRLpTEHtQ4s8lwnMd0lhg7HiZVfvEyzk54f6J0CgTV5oHzVscdAA"
}
Response samples
application/json
{
  • "payload": "string",
  • "senderDidUrl": "did:web:organization.com#2vcj3MjR4d",
  • "senderPublicJwk": { },
  • "recipientDidUrl": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
}

Send a message

Sends an encrypted JWM (JSON Web Messaging) format message to a service endpoint defined in a public DID document.

Analytic events

  • MESSAGING_SEND_START
  • MESSAGING_SEND_SUCCESS
  • MESSAGING_SEND_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
to
string

Recipient DID.

string or object

Message in JWE (JSON Web Encryption) format. This endpoint only accepts Encrypted payloads to ensure that messages are encrypted-at-rest whilst in messaging inboxes. The message should be encrypted for the recipient based on a key available in the DID Document.

Responses
200

Message sent

400

Error sending message

post/core/v1/messaging/send
Request samples
application/json
{
  • "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
  • "message": {
    }
}
Response samples
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}
➔ Next to Inboxes