How to Delete Inactive User Accounts in Matrix Synapse via Admin API

In Matrix Synapse, there is an important distinction between deleting an inactive account and deactivating it. Synapse’s documented Admin API does not provide a general-purpose hard-delete endpoint that removes every database record associated with a user. The supported administrative workflow is to identify an account, review it, then call the deactivation endpoint. You can optionally set "erase": true to remove profile information and mark the user as erased.

A good result is therefore not “the user ID disappears from every Synapse table.” A good result is that the user can no longer authenticate, active tokens and devices are removed, the account is taken out of rooms, third-party identifiers are removed, and—if your policy requires it—the profile is erased. Uploaded media and historical messages are separate concerns and are not automatically deleted by account deactivation.

This guide uses the current Synapse Admin API documentation available in October 2026. Always compare the examples with the documentation for the Synapse version running on your homeserver, especially if you operate a long-lived deployment or use Matrix Authentication Service. The authoritative references are the Synapse User Admin API documentation, the Synapse Admin API overview, and the Synapse Media Admin API documentation.

What outcome should you aim for?

Before changing anything, define the cleanup policy. “Inactive” is not a Synapse account state; it is a rule you create from fields such as last_seen_ts, account type, administrative status, and business context.

If you are unsure whether an account is abandoned, do not make last_seen_ts your only criterion. Service accounts, application-service users, emergency administrators, bots, support accounts, and SSO-linked users can have unusual login patterns. A reliable cleanup process includes an explicit exclusion list and a review step.

Step 1: List local users and collect activity data

Admin API requests require an access token belonging to a server administrator, which is different from being a room administrator. Send the token in the HTTP Authorization: Bearer header rather than placing it in a URL or shell history where possible.

Synapse documents the V3 user-list endpoint as:

GET /_synapse/admin/v3/users

A basic request looks like this:

export SYNAPSE_URL="https://matrix.example.com"
export ADMIN_ACCESS_TOKEN="REDACTED"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v3/users?limit=100"

The user-list API supports pagination. When the response contains next_token, request the next page using that value as from. Do not assume the first page represents the full server.

The API exposes useful fields for cleanup decisions, including whether an account is an admin, its user type, whether it is already deactivated, when it was created, and when it was last seen. The documentation defines last_seen_ts as the user’s last activity timestamp in milliseconds since the Unix epoch.

What counts as “inactive”?

A common policy is “no activity for 180 days,” but the right threshold depends on the environment. A small private server may reasonably use 90 days. A university, seasonal organization, or alumni service may need 365 days or more.

Use an absolute cutoff timestamp rather than comparing formatted dates. For example, a Python job can compute the threshold in milliseconds:

from datetime import datetime, timezone, timedelta

cutoff = datetime.now(timezone.utc) - timedelta(days=180)
cutoff_ms = int(cutoff.timestamp() * 1000)

Then consider a user inactive only when the account is active, non-administrative, not protected by policy, and its last_seen_ts is older than the threshold.

Treat a missing or null last-seen value conservatively. It may mean the account has never produced the activity data you expect, not necessarily that it is safe to remove. Cross-check creation time, account type, SSO mapping, and business ownership before including it.

Step 2: Build an inactivity candidate list, not an automatic deletion list

The quality of this step matters more than the speed of the API calls. Your objective should be a reviewed candidate list containing only accounts that are safe to deactivate.

At minimum, exclude:

• homeserver administrators;
• known application-service and integration accounts;
• bots and support accounts that are intentionally dormant;
• break-glass or emergency accounts;
• accounts on a legal-hold or retention exception list;
• users who recently changed identity provider or account mapping;
• already deactivated users, unless you are auditing previous cleanup work.

A simple candidate record should contain the Matrix user ID, last_seen_ts, creation timestamp, admin flag, account type, and the reason it passed the inactivity rule. Keeping this evidence makes later review and rollback decisions much easier.

How do you know the candidate selection is good enough?

Look for three signs:

• Integridad: su script ha paginado toda la lista de usuarios locales.
• Explicabilidad: cada candidato tiene una razón visible, como por ejemplo "última vez visto hace 242 días, no es una cuenta de administrador ni de servicio".
• Bajo riesgo de falsos positivos: las cuentas especiales y las excepciones comerciales se filtraron antes de cualquier llamada perjudicial.

Si no puedes superar esas comprobaciones, modifica el proceso antes de continuar. Por ejemplo, añade una fase de aprobación humana, envía una advertencia de inactividad o empieza con la suspensión en lugar de la desactivación.

Paso 3: Inspeccione cada cuenta antes de desactivarla.

Para un usuario local específico, Synapse documenta lo siguiente:

GET /_synapse/admin/v2/users/<user_id>

Ejemplo:

USER_ID="@olduser:example.com"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/$USER_ID"

La respuesta puede incluir el estado administrativo de la cuenta, indicadores de desactivación y borrado, marcas de tiempo de creación y última conexión, identidades externas e identificadores de terceros. Este es el punto para verificar que la cuenta sea la que se pretende modificar.

¿Deberías usar borrar verdadero o borrar falso?

Utilice esta opción "erase": falsecuando el objetivo operativo sea deshabilitar el acceso conservando la información del perfil. Según la documentación actual de Synapse, la desactivación normal elimina los tokens de acceso activos, el hash de la contraseña, los dispositivos y las claves de cifrado de extremo a extremo, los pushers, los ID de terceros, las membresías de salas, los datos de la cuenta, las invitaciones pendientes y la información relacionada con la validez de la cuenta.

Utilice esta "erase": trueopción cuando su política también requiera eliminar el nombre de usuario, la URL del avatar, los campos de perfil personalizados y marcar al usuario como borrado. El borrado no implica la destrucción de todo el historial de mensajes. Synapse documenta explícitamente que los mensajes enviados previamente no se eliminan mediante esta API, y que el contenido multimedia subido tampoco se elimina automáticamente.

Esa distinción es fundamental. Si su política exige la eliminación de contenido más allá del borrado del perfil, la desactivación de la cuenta por sí sola no es suficiente.

Paso 4: Realizar una prueba en seco, desactivar y verificar.

Antes de ejecutar los cambios, escriba los ID de usuario finales en un archivo de texto plano o JSON y revíselo. La prueba debe ser inmutable durante el período de cambios: si el script de generación de candidatos cambia mientras desactiva usuarios, detenga el proceso y regenere la lista aprobada.

Para cada usuario local aprobado, llame al punto final de desactivación documentado:

POST /_synapse/admin/v1/deactivate/<user_id>

Ejemplo sin borrado de perfil:

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": false}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

Ejemplo con borrado de perfil:

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": true}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

Posteriormente, vuelva a consultar la cuenta:

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/@olduser:example.com"

Un resultado operativo exitoso debería mostrar "deactivated": true. Si solicitó el borrado, verifique también "erased": true. No utilice “la API devolvió HTTP 2xx” como único criterio de éxito; lea el registro del usuario después del cambio.

¿Qué elimina realmente la desactivación?

La documentación actual de Synapse enumera varios efectos de la desactivación. Entre ellos se incluyen la eliminación de tokens de acceso activos, identificadores de terceros, dispositivos, claves de cifrado de extremo a extremo, pushers, hashes de contraseñas, membresías de salas, invitaciones pendientes y datos de la cuenta. También elimina al usuario del directorio de usuarios.

Con erase: true, Synapse elimina además el nombre para mostrar, la URL del avatar, los campos de perfil personalizados y marca la cuenta como borrada.

Synapse también documenta elementos importantes que no se eliminan con esta operación. Estos incluyen mensajes enviados y recibidos, archivos multimedia subidos, asignaciones de SSO, marcas de tiempo de creación, anulaciones de límites de velocidad, registros mensuales de usuarios activos y cierta información de consentimiento. La lista documentada no es necesariamente exhaustiva, por lo que la desactivación debe considerarse como el cierre de la cuenta, no como una eliminación total de datos.

¿También necesitas eliminar los archivos multimedia subidos por el usuario?

Si su política de retención requiere eliminar los archivos multimedia almacenados localmente y subidos por el usuario, Synapse proporciona un punto final independiente:

DELETE /_synapse/admin/v1/users/<user_id>/media

Ejemplo:

curl -sS -X DELETE   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v1/users/@olduser:example.com/media"

La API de medios de usuario elimina los archivos multimedia locales y las miniaturas almacenadas en el repositorio de medios de Synapse. La documentación indica dos limitaciones importantes para el funcionamiento. En primer lugar, los archivos multimedia almacenados en un repositorio externo no se ven afectados por esta API. En segundo lugar, si no se establece un límite, el punto final elimina 100 archivos por solicitud, por lo que los usuarios con un historial de archivos multimedia extenso pueden requerir varias llamadas.

No actives la eliminación automática de archivos multimedia a menos que tu política de retención así lo exija. Es mucho más perjudicial que la desactivación de la cuenta y puede afectar a los archivos multimedia que aún se encuentran en las salas históricas.

¿Cuándo debería utilizarse la suspensión en su lugar?

Synapse también documenta una API para la suspensión de cuentas. La suspensión bloquea actividades como enviar mensajes, unirse a salas, enviar invitaciones, modificar la información del perfil y la mayoría de las censuras, manteniendo una ruta de recuperación diferente a la de la desactivación.

La suspensión es más apropiada cuando se necesita una retención administrativa reversible, cuando la inactividad es incierta o cuando aún se está llevando a cabo una revisión de baja. La desactivación es la mejor opción cuando se debe finalizar el acceso y eliminar tokens, dispositivos, membresías de salas y datos de cuenta.

Para la limpieza automatizada, una política por etapas suele ser más segura:

1. marcar una cuenta después de que haya superado el umbral de inactividad;
2. notificarlo o revisarlo;
3. Suspéndalo si la propiedad es incierta;
4. Desactivar únicamente una vez transcurrido el plazo de retención o aprobación.

¿Cómo se debe automatizar la limpieza de forma segura?

Mantenga la detección y la desactivación como tareas separadas. La tarea de detección debe ser de solo lectura y generar un archivo candidato. La tarea de ejecución debe consumir únicamente los archivos aprobados y registrar el estado de cada solicitud y respuesta.

Un flujo de trabajo con calidad de producción también debería:

• seguir todos los tokens de paginación;
• limitar la velocidad de las solicitudes masivas en lugar de enviar miles simultáneamente;
• Se excluyen de forma predeterminada los administradores del servidor y las cuentas de servicio con nombre;
• almacenar marcas de tiempo en UTC;
• registre la versión de la política de limpieza que seleccionó para cada cuenta;
• Se detiene en caso de errores de autenticación, autorización o errores repetidos del servidor;
• volver a consultar a cada usuario después de su desactivación;
• Mantenga los tokens de acceso administrativo fuera del código fuente y los registros.

Si la verificación posterior al cambio no coincide con el estado solicitado, no continúe sin más con el lote restante. Investigue los primeros fallos y determine si el problema se debe a permisos, compatibilidad de la versión de la API, un problema de configuración del proxy, la integración con el Servicio de Autenticación de Matrix o una condición específica de la cuenta.

Lista de verificación final

• Utilice un token de portador de administrador del servidor.
• Enumera todas las páginas de usuarios locales, no solo las de los primeros 100 usuarios.
• Defina la inactividad con un umbral y exclusiones documentados.
• Inspeccione individualmente las cuentas de alto riesgo antes de tomar cualquier medida.
• Generar y aprobar una lista de prueba.
• Utilice el punto final de desactivación en lugar de asumir que Synapse admite la eliminación completa de la cuenta.
• Seleccione esta opción erase: trueúnicamente cuando la eliminación del perfil forme parte de la política.
• Gestionar los archivos multimedia subidos por separado cuando sea necesario.
• Verificar deactivatedy, cuando corresponda, eraseddespués de cada cambio.

La limpieza más fiable es aquella que se puede explicar posteriormente: qué regla de inactividad seleccionó una cuenta, qué excepciones se comprobaron, qué acción de API se realizó y qué campo posterior al cambio demostró el estado deseado. Este estándar es más útil que simplemente maximizar el número de cuentas procesadas en una sola ejecución.