Overview
Most communication systems require participants to share personal identifiers such as an email address or phone number before exchanging messages. This ties communication to a central platform and gives the platform operator visibility into who is communicating with whom.
Affinidi Messaging is built on the DIDComm v2.1 open standard and W3C Decentralised Identifiers. Parties are identified by cryptographic keys rather than personal details. Messages are end-to-end encrypted and routed through a mediator that handles delivery without accessing message content.
The result is a transport-agnostic communication layer that works for human conversations, agent-to-agent calls, and verifiable credential exchange on the same channel, without requiring a central platform or personal identifiers to establish trust. Integrate Affinidi Messaging into your application →
What is DIDComm
The DIDComm v2.1 protocol is an open standard for decentralised communication. It is built on Decentralised Identifiers (DIDs), which allow parties to exchange verifiable data such as credentials and establish secure communication channels without relying on centralised servers.
DIDComm works seamlessly with the Self-Sovereign Identity (SSI) model. It acts as the communication layer that gives users full control over their privacy and identity during digital interactions.
DIDComm v2.1 unlocks several key capabilities for secure, decentralised communication:
Verifiable Credential Exchange: Supports trusted issuance, transmission, and verification of digital credentials between holders and verifiers. This ensures data integrity and authenticity.
Encrypted AI Agent Communication: Enables confidential, end-to-end encrypted messaging between AI agents across different environments and transport layers.
Decentralised API Layer: Provides a secure, message-based alternative to traditional REST APIs. It offers strong message-level encryption that goes beyond standard transport-layer security.
Why use DIDComm
Trusted Digital Interaction: DIDComm uses DIDs to sign and verify message authenticity. Both parties can authenticate each other, reducing fraud risks, especially when interacting with businesses or AI agents.
Privacy by Design: Messages are sent with end-to-end encryption by default, minimising metadata exposure. This ensures that only the intended recipient can access the message content, while the messaging server or mediator has no visibility into it.
End-to-end Encryption: Messages are encrypted using public key cryptography. The recipient’s public key, published via DID, ensures only the intended recipient can decrypt the content.
Interoperable and Transport-Agnostic: DIDComm works across devices and channels, including HTTP, WebSockets, and Bluetooth. It does not rely on transport security for trusted communication.
Flexible Implementation: DIDComm is modular and extensible. It supports diverse use cases, including RESTful APIs, and integrates with open standards like OID4VCI and OID4VP for credential exchange.
Key components
Decentralised Identifier (DID)
A DID is a globally unique identifier that enables secure interactions. It is central to Self-Sovereign Identity (SSI), which gives individuals control over their digital identity.
DID resolution produces a DID Document containing public key details for encryption and verification, as well as service endpoints for authentication and messaging.
DIDComm Message
A JSON Web Message (JWM) is a lightweight, secure, and standardised format for structured communication using JSON. It includes headers, message types, routing metadata, and payloads designed to enable secure and interoperable communication across different systems.
Message format
The DIDComm message format defines how messages are structured for secure, interoperable communication between parties within a decentralised ecosystem.
{
"id": "9c8dcdc3-b41c-46ed-8bae-9dd3ce016568",
"typ": "application/didcomm-plain+json",
"type": "https://affinidi.com/didcomm/protocols/1.0/data-response",
"body": {
"response_requested": true
},
"from": "did:peer:2.VzDnaecahsBv8WxteYAUfn8cSzZmZ5DKhtfLT1uKW52MpNzauu...",
"to": [
"did:web:mediator.example.com"
],
"thid": null,
"pthid": null,
"extra_headers": {},
"created_time": 1761540161,
"expires_time": 1761540461,
"from_prior": null,
"attachments": []
}Key properties of the DIDComm Message:
| Property | Description |
|---|---|
| id | A unique message ID across all messages in the mediator. |
| type | A URI or a string that references a message schema or protocol definition. It helps agents understand how to process the message. |
| to | An array list of DIDs of the recipients. |
| from | The DID of the sender. |
| thid / pthid | Threading fields for message context, such as reply threads and conversation grouping. |
| expires_time | The message expiry time used by the sender when they will consider the message as “expired”. |
| attachments | Contains external content within a message, such as documents, credentials, images, or other data, without embedding them directly in the message body. |
For more details about the structure of DIDComm Message, refer to the Plaintext Message Structure section of the DIDComm v2.1 specification.
DIDComm Envelopes
DIDComm messages can be composed into different formats, plaintext, signed, and encrypted. Within the DIDComm protocol, these formats are referred to as envelopes.
Plaintext
A message that is neither signed nor encrypted. Readable by anyone, with no integrity or authenticity guarantees.
Use when: Non-sensitive data, debugging, or as inner content wrapped by a signed or encrypted envelope.
Signed
Digitally signed but not encrypted. Anyone can read it, but the recipient can cryptographically prove who signed it. This property is called non-repudiation: the sender cannot deny having sent the message.
Use when: The message's origin must be verifiable to the recipient or third parties.
Encrypted
Sealed for one or more recipients. Uses either authenticated or anonymous encryption.
- authcrypt: proves sender identity to the recipient, not to intermediaries.
- anoncrypt: hides sender identity from the recipient and intermediaries.
Use when: Only the intended recipients should be able to read the message.
Combining DIDComm Envelopes
DIDComm envelopes can be nested to achieve specific combinations of the following security properties:
Confidentiality: Ensures that only intended recipients can read the message content. Mediators and intermediaries cannot access its contents.
Sender Authenticity: Allows recipients to verify the identity of the sender, ensuring the message originates from a trusted source.
Non-repudiation: Prevents the sender from denying that they sent the message, thanks to cryptographic signing.
Sender Anonymity: Protects the sender’s identity from being exposed to mediators or intermediaries during message routing.
Each combination below shows the security properties it provides. Choose based on your application’s requirements.
plaintextNo security properties. Readable by anyone.
signed(plaintext)anoncrypt(plaintext)authcrypt(plaintext)authcrypt(sign(plaintext))anoncrypt(authcrypt(plaintext))anoncrypt(sign(plaintext))
All propertiesFor the full list of envelope media types, see IANA Media Types in the DIDComm v2.1 specification.
Mediator (Agents)
A mediator is a messaging server that routes messages securely between parties, such as individuals, businesses, or AI agents. Mediators cannot access message content.
Mediators provide capabilities such as:
Message Routing: Mediators handle encrypted forward messages and pass them on to the intended recipient. The message remains fully end-to-end encrypted, ensuring that the mediator cannot access or read its contents.
Message Storage & Pickup: Temporarily store messages and enable asynchronous communication.
A DIDComm mediator works like a decentralised SMTP relay, ensuring privacy, integrity, and independence from transport protocols.