Matrix Federation Delegation Profile: Well-Known JSON vs. DNS SRV Records
Running a Matrix homeserver alongside an existing community domain requires routing server-to-server traffic effectively. In decentralized communication setups, administrators often want user handles that align with their primary apex domain without hosting the backend daemon directly on that base address. According to the Delegation - Synapse documentation, homeservers resolve these connection targets using either HTTP-based delegation or DNS SRV records.
At a Glance: The Federation Routing Baseline
Matrix identifies servers using a configuration value known as server_name. This name forms the suffix of user identifiers and room aliases, indicating to remote instances where federation requests should go. By default, federating homeservers attempt to discover and establish connections with target domains on port 8448 over HTTPS.
If an organization registers example.com, user addresses follow the format @user:example.com. In a standard setup without delegation, remote instances attempt to reach that server directly at https://example.com:8448/. When hosts wish to keep addresses matching *:example.com while transferring traffic to a dedicated target like synapse.example.com:443, they implement federation delegation.
The Well-Known JSON Delegation Mechanism
The primary delegation method relies on serving a structured JSON file over standard web traffic. A server positioned at the base domain serves this file over port 443 at the endpoint path https://<server_name>/.well-known/matrix/server. The payload supplies the federation target using the m.server key:
{
"m.server": "synapse.example.com:443"
}
Supplying the target port inside the value string is optional; if the port is left out, federation requests automatically default back to port 8448. Community administrators running systems like those reviewed in our Synapse Matrix Homeserver Profile can deploy this file through two architectural paths:
- External Web Server or Reverse Proxy: Services such as HAProxy, Apache, or environments configured via an NGINX proxy architecture handle incoming requests on port 443 and return the static delegation JSON response. This provides broad deployment flexibility.
- Synapse Built-in File Delivery: When traffic to the base
https://<server_name>address routes directly into Synapse itself, administrators can activateserve_server_wellknown: truewithin thehomeserver.yamlconfiguration file. However, this internal flag only works if the apex domain points to Synapse, making it unsuitable when hosting on a distinct subdomain.
The DNS SRV Record Alternative and Its Constraints
The Matrix specification also allows federation routing via DNS SRV records. Rather than querying an HTTPS endpoint on port 443, remote homeservers query DNS zone entries to determine the target host and port for server-to-server handshakes. Despite being technically viable, this approach is generally not recommended by official Synapse documentation.
The primary barrier with SRV records involves TLS certificate validation. Configuring matching certificates correctly across federating hosts can prove difficult when routing across distinct record targets. Furthermore, DNS delegation provides minimal practical advantage compared to the simplicity of serving a lightweight JSON document.
Crucially, DNS SRV delegation only resolves server-to-server traffic. It provides no mechanism for client-server communication. Global client settings—such as assigning a default Jitsi endpoint or ensuring new rooms are not created as encrypted by default—require client-facing files served from spec-defined .well-known paths on the apex domain. Relying exclusively on SRV records deprives administrators of centralized client configurations, leaving settings to the standalone feature sets of individual user clients.
Architectural Comparison: JSON File vs. DNS SRV
When selecting a delegation strategy for community infrastructure, administrators weigh distinct trade-offs between transport layers:
- Protocol and Port Requirements: Well-known delegation requires an HTTPS server reachable on default port 443. SRV delegation avoids hosting web files at the apex domain, relying instead on authoritative DNS records.
- Certificate Simplicity: Well-known routing keeps TLS configurations straightforward on both the apex proxy and target hosts. DNS SRV setups complicate TLS validation across federated connection points.
- Client Configuration Parity: Well-known hosting endpoints can serve both server discovery data and global client settings. DNS SRV records cannot serve client settings, restricting centralized management of room defaults.
- Reverse Proxy Utility: Passing federation traffic through an external reverse proxy is broadly advantageous under both setups, as offloading TLS termination preserves server resources in Synapse.
When Delegation Is Not Required
Homeservers do not always need delegation. According to the Delegation - Synapse documentation, if an admin points the base DNS A record of example.com straight to a dedicated host, runs Synapse there, and routes port 8448 through a reverse proxy serving TLS certificates for example.com, no delegation is necessary. Delegation is only required when the public API cannot reside on port 8448 of the domain defined by the server_name setting.
Sources
Published October 30, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.