Mediator Operating Modes

You can configure your DIDComm Mediator to operate in different modes based on how you want it to handle messages and interactions between participants.

To configure the mediator-level Access Control Lists (ACLs), edit the file conf/mediator.toml on the server hosting the mediator.

Apply the changes and restart the mediator to activate the new configuration.

Private Mediator – Closed Network

The strictest and most controlled mediator configuration.

This is the strictest configuration. It creates a private messaging network where users can only communicate with authorised contacts defined by the administrator. Each user’s DID must be added to the mediator to establish permissions.

Example: A business running a private network for staff working on a confidential merger. Alice and Bob can message their manager but cannot message each other.

        
### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_allow}

        
### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:DENY_ALL,LOCAL,SEND_MESSAGES,RECEIVE_MESSAGES}

        
### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:true}"

Private Mediator – Open Network

An internal network where users can freely communicate within the company. Each user’s DID must still be explicitly allowed by the administrator.

        
### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_allow}

        
### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL}

        
### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:true}"

Public Mediator – Closed Network

The recommended operating mode for most mediators allows any user to connect unless the administrator explicitly denies access. However, for a user to send messages to another user, the recipient must explicitly permit the sender’s DID for message delivery. In other words, the recipient’s consent is required before messages can be received.

This mode helps protect users from unknown senders spamming or sending unsolicited messages.

It also relies on the forwarding mechanism for all message delivery, adding an extra layer of abstraction to routing and destination handling across the network.

        
### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_deny}

        
### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL,MODE_EXPLICIT_ALLOW}

        
### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:false}"

Public Mediator – Open Network

The most open configuration.

The most open configuration. Any user can connect, send, and receive messages without restrictions unless ACLs are updated by the user (if permitted by the administrator).

Spam and unsolicited message handling must be managed by the client app or DIDComm agent, as the mediator only relays messages.

        
### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_deny}

        
### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL}

        
### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:false}"

Public Mediator – Mixed Mode

The mixed mode allows the mediator to operate on open and closed networks.

It allows the mediator to accept unknown messages to enable discovery and initiate connections between users using an ephemeral DID. Once the connection is established, users switch to private DIDs to start communicating with each other. The private DIDs are added to the Access Control Lists (ACLs), which will allow message delivery between users.

        
### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_deny}

        
### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL,MODE_EXPLICIT_ALLOW}

        
### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:false}"

In the case of Out-Of-Band (OOB) discovery, it uses two different DIDs to facilitate discovery:

1. An ephemeral DID that is published in the OOB Invitation. It must be open to the world.

2. A private channel DID that is closed to the world, except for the DID discovered through the OOB discovery protocol.

The ephemeral DID would change its ACL flags to the following:

• acl_flags: ALLOW_ALL (which also forces MODE_EXPLICIT_DENY)

The private channel DID follow the existing global_acl_default.

What’s Next