light-mode-image
Learn
API ReferenceMessaging

Encrypt a message

Roles

adminissuermanaged-issuer

Analytics Events

MESSAGING_ENCRYPT_STARTMESSAGING_ENCRYPT_SUCCESSMESSAGING_ENCRYPT_FAIL
POST/v1/messaging/encrypt

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

Analytic events

  • MESSAGING_ENCRYPT_START
  • MESSAGING_ENCRYPT_SUCCESS
  • MESSAGING_ENCRYPT_FAIL

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

Encryption parameters

senderDidUrl*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*array<>

The intended recepient's Subject DID.

payload*object

The message to be encrypted.

Response Body

application/json

application/json

curl -X POST "https://example.vii.au01.mattr.global/v1/messaging/encrypt" \  -H "Content-Type: application/json" \  -d '{    "senderDidUrl": "did:web:learn.vii.au01.mattr.global#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",    "recipientDidUrls": [      "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",      "did:key:z6MkgxxdrThaRd7HbeAA4pYEwAgKT6ZXy2aNTcPkmeF1yWHN"    ],    "payload": {      "id": "731961f2-bdc3-4f1e-8d59-cc308fd60ec8",      "type": "https://mattr.global/schemas/verifiable-credential/offer/OidcCredentialProvider",      "from": "did:web:learn.vii.au01.mattr.global",      "created_time": 1616466734,      "body": {        "uri": "openid://discovery?issuer=https://tenant.vii.mattr.global/ext/oidc/v1/issuers/0dceeddd-f717-4bf2-b520-b3ddcd104a60"      }    }  }'
{
  "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"
      },
      {
        "header": {
          "alg": "ECDH-1PU+A256KW",
          "kid": "did:key:z6MkgxxdrThaRd7HbeAA4pYEwAgKT6ZXy2aNTcPkmeF1yWHN#z6LSgDiT1CkducmcSPaq9E1Uj1qdSXBjsUNqqLQLrUu8EHWd",
          "epk": {
            "kty": "OKP",
            "crv": "X25519",
            "x": "gDYW7rhG3cBqFp9trFETtlut6QJxYVVSoVWL7eN1bzE"
          },
          "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
        },
        "encryption_key": "F5R5ZW7Yk7_iWT5kUWqv3w_tLI7V86tLRthjy_SSbGQ2pFyXKni_gA"
      }
    ],
    "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
    "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
    "tag": "u8kT0VAAtTswjGXxNpuX0g=="
  }
}
{
  "code": "BadRequest",
  "message": "Validation Error",
  "details": [
    {
      "location": "body",
      "msg": "Resource Not Found",
      "param": "senderDidUrl",
      "value": "did:key:z6MkopLiuMudqeRm1KvQ24jyUfn6pciePNomKqpsiMgeg4nT#z6LSmWEcPwNbxCgbuSMGTz1Gddnf9MsVSMJCfgPtksgThLvi"
    }
  ]
}

How would you rate this page?

Verify a message POST

Verifies the signature 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

Decrypt a message POST

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