Establishing an Administrative Recovery Account Policy Using the Synapse User API
Running a Matrix homeserver alongside your community platform offers private, real-time messaging, but maintaining administrative continuity is critical. If your primary administrator loses credentials, community operations can stall completely. To keep your deployment resilient, you need a documented recovery account framework. By understanding how to properly bootstrap server credentials and use administrative endpoints, operators can protect access without risking database integrity.
Bootstrapping the Primary Recovery Operator
When deploying Synapse, administrators often face a classic bootstrapping challenge: you cannot promote users through the administrative endpoints until an active administrator exists. According to the Synapse Admin FAQ, if your homeserver does not have an admin account yet, you will not be able to call the administrative endpoints directly. In this initial setup phase, you must edit the database manually to configure your initial administrator.
Synapse documents the exact SQL statement required to grant administrative rights directly in your database:
UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
Directly modifying database tables carries inherent risks for ongoing operations. The official documentation advises that manually editing the database is generally not recommended once an initial administrative account exists. After establishing this primary recovery account, all subsequent promotions, permission updates, and account resets must be performed through the official APIs rather than raw database writes. For broader guidance on securing administrative accounts across your stack, check our forum admin security steps.
Promoting Backup Accounts via the User Admin API
To avoid single-operator lockouts, community infrastructure policies should require at least one designated backup administrator. Synapse guidelines establish that once an initial admin account exists, you should use the User Admin API to promote other accounts to become admins. Transitioning from database queries to structured API requests ensures internal state consistency and leaves an audit trail in your server logs.
Establishing an administrative recovery account policy means setting rules for:
- Secondary Admin Designation: Promoting a trusted secondary profile or offline emergency account using the User Admin API rather than database commands.
- Credential Management: Defining protocols for password resets. While users can reset credentials through their client, a server admin can also reset a user's password directly using the admin API.
- Access Auditing: Periodically verifying which profiles hold administrative privileges and checking active accounts against server records.
Server State Auditing and Troubleshooting
Your administrative policy should define specific read-only database queries to maintain visibility over your installation during recovery scenarios. When verifying user states or assessing external connections, the Synapse Admin FAQ provides concrete queries that can be safely executed on your database:
- Listing Registered Users: Run
SELECT NAME from users;to audit all accounts registered on the server. - Reviewing Server Destinations: Run
SELECT * FROM destinations;to see what remote servers your homeserver is communicating with. - Inspecting Room Participants: To check which servers are participating in a room, run:
SELECT DISTINCT split_part(state_key, ':', 2) FROM current_state_events WHERE room_id = '!cURbafjkfsMDVwdRDQ:matrix.org' AND membership = 'join'; - Identifying Largest Rooms: You can audit database load by querying room sizes with
SELECT s.canonical_alias, g.room_id, count(*) AS num_rows FROM state_groups_state AS g, room_stats_state AS s WHERE g.room_id = s.room_id GROUP BY s.canonical_alias, g.room_id ORDER BY num_rows desc LIMIT 10;(or use the List Room API ordered bystate_events).
Audit Trails and Log Verification
Account recovery procedures must always include log verification to confirm when administrative actions were taken and identify who executed them. Synapse tags every HTTP request line in its logs with a method identifier such as GET-, PUT-, POST-, OPTIONS-, or DELETE-.
When an administrative request completes, Synapse writes a log line containing the text Processed request:. For instance, a finished request tagged with GET-37 can be isolated in your log files using standard utilities:
grep 'GET-37' homeserver.log
By monitoring these log patterns, server owners can audit all recovery actions, match inbound administrative calls against completion entries, and flag unexpected administrative operations promptly. Learn more about managing authentication logs safely in our forum admin logging checklist.
Room Access Cleanups and Emergency Safeguards
Administrative recovery occasionally involves cleaning up broken permissions or orphaned aliases. If room access is compromised, administrators can delete an alias using an administrative curl request:
curl -H 'Authorization: Bearer <access-token>' -X DELETE https://matrix.org/_matrix/client/r0/directory/room/<room-alias>
When facing severe server issues, operators might feel tempted to wipe the database and start over. Synapse documentation strongly warns against this: deleting your database is unlikely to make anything better. In a federated network, remote servers retain information about your homeserver, leading to broken room states. The documentation lists only two exceptions where resetting a database makes sense: if your server has never joined federated rooms with other servers, or if you are changing the server_name setting in your homeserver configuration. Outside of those situations, maintain your database and resolve account issues strictly through administrative endpoints.
Sources
Published October 30, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.