DIDComm messaging

How the Agent Gateway uses DIDComm v2.1 for end-to-end encrypted gateway-to-gateway messaging and federation.

The Agent Gateway uses DIDComm v2.1 as the encrypted transport layer for gateway-to-gateway federation. Every message is end-to-end encrypted, authenticated via the sender’s DID, and routable without a shared network or VPN. Connect two gateways →

What DIDComm provides

  • End-to-end encryption: Messages are encrypted to the recipient’s DID keys using X25519 key agreement. Only the intended recipient can decrypt.
  • Authenticated messaging: Sender identity is verified via DID. The gateway resolves the sender’s DID document and verifies the message signature.
  • Transport agnostic: DIDComm works over HTTP, WebSocket, or any other transport.
  • Routing through mediators: Messages can be relayed through mediators on behalf of agents that may be temporarily offline.
  • Decentralised: No central authority. Parties communicate directly using DIDs.

DID document

The gateway publishes its DID document at /.well-known/did.json. This is required for did:web resolution by remote parties. The document includes:

  • Ed25519 verification methods for message signing and authentication.
  • X25519 and P-256 key agreement keys for establishing encrypted channels.
  • A DIDComm service endpoint identifying where DIDComm messages should be delivered.
  • Service entries for any surfaces configured to publish to the DID document.

For the gateway’s did:web document to be resolvable by remote parties, the gateway must be reachable at a publicly accessible HTTPS URL. The gateway’s domain is configured in gateway.json.

Message flow

Messages encrypted for the gateway’s keys arrive at the DIDComm messaging endpoint. The gateway decrypts the message, identifies the recipient surface, and forwards the decrypted payload.

    Agent A → [Encrypt with B's key] → Gateway A → [Route] → Gateway B → [Decrypt] → Agent B

For gateway-to-gateway routing, both gateways exchange out-of-band (OOB) invitations to establish a connection. After connection, traffic is routed using Gateway Connection (fabric:// URIs that reference the connection point and remote surface ID).

Out-of-band connection establishment

Connections between gateway instances use the Out-of-Band (OOB) protocol. One gateway generates an OOB invitation URL and shares it with the remote gateway operator. The remote gateway imports the URL, and the two gateways automatically exchange DIDComm handshake messages to establish a shared session. Once active, surfaces on either gateway can route traffic to surfaces on the other using Gateway Connection (fabric:// URIs).

OOB invitations expire after 24 hours. Complete the connection setup within this window.

Mediator support

The gateway can act as a DIDComm mediator, receiving and storing messages on behalf of agents that may be offline, then delivering them when the agent reconnects. Mediator configuration is required when agents cannot maintain persistent connections to the gateway.

Public accessibility

For DIDComm to work across the internet, the gateway’s DID document and message endpoint must be publicly reachable. During development, a tunnelling tool can be used to expose a local gateway instance. The tunnel URL is set as the gateway’s proxy domain so the generated DID document points to the public address.

  • Architecture: How DIDComm fits into the gateway’s internal component model.
  • Gateways: How gateway instances connect to each other using DIDComm tunnels.
  • Agent identity and DIDs: How the gateway’s own DID is established.