Auditing Synapse Users: Metadata, Sessions, and Bans

By 4FreeForums Editors · Published October 31, 2026 · Sources linked below

Running a Matrix homeserver alongside your community platform gives your members real-time chat, but it also introduces the need for robust user moderation and security controls. When rogue accounts, spam runs, or account takeovers occur, server administrators need programmatic tools to audit account details, monitor active devices, and terminate abusive access. The Synapse administrative interface provides dedicated HTTP endpoints to handle account discovery, forensic lookups, and session revocation.

How Do Administrators Authenticate and Query Specific User Accounts?

To interact with any administrative route, your client must authenticate by submitting an access_token associated with an administrator account on the homeserver. With credentials established, inspecting the details of an individual user is handled through an HTTP GET request directed at /_synapse/admin/v2/users/<user_id>, passing a fully-qualified Matrix identifier like @user:server.com.

According to the Users - Synapse documentation, this lookup returns a JSON payload detailing core metadata and moderation flags. The returned fields include:

• Profile details: name, displayname, and avatar_url (both of which can be null if unset).
• Account flags: is_guest, admin, deactivated, erased, shadow_banned, locked, and suspended.
• Activity metrics: creation_ts (such as 1560432506) and last_seen_ts (such as 1732919539393).
• Linked third parties: threepids containing an array of bound contact points with their medium (such as email), address, added_at, and validated_at timestamps.
• Single sign-on mappings: external_ids arrays showing the associated auth_provider and mapped external_id.
• Policy metadata: user_type, appservice_id, and consent values such as consent_version, consent_server_notice_sent, and consent_ts.

How Does Account Discovery and Pagination Work Across the Server?

When investigating broader abuse incidents or conducting routine administrative reviews, administrators can list all registered local accounts via the GET /_synapse/admin/v2/users endpoint. If you are comparing communication platforms or transitioning from threaded boards, understanding session flows and identity storage mirrors practices found across our Forum Admin Security: 10 Steps to Protect Your Forum From Takeovers guide.

The endpoint supports fine-grained URL query parameters for filtering and navigation:

• user_id and name: Filter records by user ID or match against user ID localparts and display names.
• guests: Controls guest inclusion; it defaults to true, while setting it to false excludes guests. However, setting this option to true is not supported when Matrix Authentication Service integration is enabled.
• admins: An optional flag where true queries only administrators, false excludes them, and omitting the flag includes both.
• deactivated: Defaults to false to omit deactivated users; setting it to true includes them. Note that under the newer GET /_synapse/admin/v3/users endpoint, deactivated=true returns only deactivated users, false excludes them, and leaving it absent applies no filter.
• locked: Introduced in version 1.93, defaults to false, and includes locked users when set to true.
• limit and from: Controls pagination size (defaults to 100) and pagination offset (defaults to 0). Administrators should treat from as an opaque value populated strictly from the previous call's next_token string. When no next_token appears in the response, pagination is complete.
• order_by and dir: Determines sorting fields and direction (f for forwards, b for backwards). Default sorting is by name. Synapse cautions that the database only has indexes on the columns name and creation_ts. Sorting by fields such as is_guest, admin, user_type, deactivated, shadow_banned, avatar_url, or displayname can cause large database loads in high-volume environments.

How Can Admins Query Active Sessions and Connections?

Investigating suspicious logins or tracking an active compromise requires viewing physical client sessions. Synapse provides two endpoints for querying active user sessions:

• GET /_synapse/admin/v1/whois/<user_id>
• GET /_matrix/client/r0/admin/whois/<userId>

The endpoint outputs the active user ID and device blocks holding an array of active connections. Each connection item records the connecting ip (such as 1.2.3.4), the browser or client user_agent, and a last_seen timestamp measured in milliseconds since the Unix epoch. Reviewing these fields allows administrators to pinpoint uncharacteristic geographic origins, unexpected user agents, or automated scrapers interacting with the server.

How Are Account Modifications and Mass Device Logouts Executed?

To update an existing account or provision a new one, administrators send a PUT /_synapse/admin/v2/users/<user_id> request. Synapse returns an HTTP 201 status code when creating a new user record and an HTTP 200 code when modifying an existing profile. Modifying administrative access and reviewing server accounts is a critical component of running real-time infrastructure, as outlined in our Synapse Matrix Homeserver Profile: Decentralized Community Chat.

The body parameters accept several operational switches:

• password: Updates the user password. Supplying a new password immediately logs out all active devices by default.
• logout_devices: Defaults to true. Setting this parameter to false prevents active devices from being logged out when a new password is provided.
• displayname and avatar_url: Setting either of these fields to an empty string ("") clears the user's display name or removes the avatar MXC URI.
• threepids: Replaces the user's third-party contacts. Each entry requires a medium (email or msisdn) and an address (for example, international numbers such as 447470274584 or 19254857364). Synapse attempts to remove removed third-party IDs from any identity servers with an existing binding.
• user_type: Accepts bot, support, custom configuration values, or null to clear the classification. Normal users default to None.
• locked: Explicitly locks the account when set to true.

What Happens When Deactivating or Suspending an Abusive Account?

When malicious activity requires full remediation, administrators have two distinct mechanisms: account suspension or complete deactivation.

To pause an account without destroying its records, administrators call PUT /_synapse/admin/v1/suspend/<user_id> with {"suspend": true}. While suspended, the user is barred from sending invites, knocking on or joining rooms, writing messages, altering profile data, or redacting messages other than their own.

For permanent termination, administrators invoke POST /_synapse/admin/v1/deactivate/<user_id>. As detailed in the Users - Synapse documentation, passing the optional JSON body {"erase": true} marks the user as GDPR-erased, ensuring messages remain visible only to members present in a room when they were sent, while hiding them from users joining later.

Deactivating an account executes extensive cleanup across the database:

• Attempts to unbind 3PIDs from the identity server and purges all 3PIDs from the homeserver.
• Deletes all devices, end-to-end encryption (E2EE) keys, pushers, and access tokens.
• Wipes the password hash and removes account validity records.
• Removes the user from the user directory, rejects pending invites, and evicts the account from all rooms.
• Clears account data, including ignored user lists, push rules, secret storage keys, and cross-signing keys.
• When erase is true, removes the display name, avatar URL, and custom profile fields.

Synapse does not delete sent and received messages, does not delete uploaded media, does not wipe SSO ID mappings, does not clear user consent timestamps or versions, and preserves the original creation timestamp.

Sources

• Users - Synapse

Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.