Como excluir contas de usuário inativas no Matrix Synapse por meio da API de administrador

No Matrix Synapse, existe uma distinção importante entre excluir uma conta inativa e desativá-la . A API de administração documentada do Synapse não fornece um endpoint de exclusão permanente de uso geral que remova todos os registros do banco de dados associados a um usuário. O fluxo de trabalho administrativo recomendado consiste em identificar uma conta, revisá-la e, em seguida, chamar o endpoint de desativação. Opcionalmente, você pode configurar "erase": truepara remover as informações do perfil e marcar o usuário como excluído.

Um bom resultado, portanto, não é "o ID do usuário desaparecer de todas as tabelas do Synapse". Um bom resultado é que o usuário não possa mais se autenticar, os tokens e dispositivos ativos sejam removidos, a conta seja retirada das salas, os identificadores de terceiros sejam removidos e — se sua política exigir — o perfil seja apagado. Mídias enviadas e mensagens antigas são questões separadas e não são excluídas automaticamente com a desativação da conta.

Este guia utiliza a documentação atual da API de administração do Synapse, disponível em outubro de 2026. Sempre compare os exemplos com a documentação da versão do Synapse em execução no seu servidor doméstico, especialmente se você opera uma implantação de longa duração ou utiliza o Matrix Authentication Service. As referências oficiais são a documentação da API de administração de usuários do Synapse , a visão geral da API de administração do Synapse e a documentação da API de administração de mídia do Synapse .

Qual resultado você deve almejar?

Antes de alterar qualquer coisa, defina a política de limpeza. "Inativo" não é um estado da conta Synapse; é uma regra que você cria a partir de campos como last_seen_tstipo de conta, status administrativo e contexto de negócios.

Se você não tiver certeza se uma conta foi abandonada, não use last_seen_tsisso como único critério. Contas de serviço, usuários de serviços de aplicativos, administradores de emergência, bots, contas de suporte e usuários vinculados a SSO podem apresentar padrões de login incomuns. Um processo de limpeza confiável inclui uma lista de exclusões explícita e uma etapa de revisão.

Etapa 1: Liste os usuários locais e colete dados de atividade.

As solicitações da API de administração exigem um token de acesso pertencente a um administrador do servidor , que é diferente de ser um administrador de sala. Envie o token no Authorization: Bearercabeçalho HTTP em vez de colocá-lo em uma URL ou no histórico do shell, sempre que possível.

O Synapse documenta o endpoint da lista de usuários V3 da seguinte forma:

GET /_synapse/admin/v3/users

Uma solicitação básica se parece com isto:

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"

A API de lista de usuários suporta paginação. Quando a resposta contiver next_token, solicite a próxima página usando esse valor como from. Não assuma que a primeira página representa todo o servidor.

A API expõe campos úteis para decisões de limpeza, incluindo se uma conta é de administrador, seu tipo de usuário, se já está desativada, quando foi criada e quando foi vista pela última vez. A documentação define last_seen_tscomo o registro de data e hora da última atividade do usuário em milissegundos desde a época Unix.

O que é considerado “inativo”?

Uma política comum é "nenhuma atividade por 180 dias", mas o limite ideal depende do contexto. Um pequeno servidor privado pode usar 90 dias sem maiores problemas. Já uma universidade, uma organização sazonal ou um serviço de ex-alunos podem precisar de 365 dias ou mais.

Use um timestamp de corte absoluto em vez de comparar datas formatadas. Por exemplo, um job em Python pode calcular o limite em milissegundos:

from datetime import datetime, timezone, timedelta

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

Considere um usuário como inativo somente quando a conta estiver ativa, não for administrativa, não estiver protegida por nenhuma política e for last_seen_tsmais antiga que o limite estabelecido.

Trate um valor de "última visualização" ausente ou nulo com cautela. Isso pode significar que a conta nunca gerou os dados de atividade esperados, e não necessariamente que seja seguro removê-la. Verifique a data de criação, o tipo de conta, o mapeamento de SSO e a propriedade da empresa antes de incluí-la.

Etapa 2: Crie uma lista de candidatos à inatividade, não uma lista de exclusão automática.

A qualidade desta etapa é mais importante do que a velocidade das chamadas à API. Seu objetivo deve ser uma lista de candidatos revisada contendo apenas contas que podem ser desativadas com segurança.

No mínimo, exclua:

• administradores de servidores domésticos;
• contas de integração e serviços de aplicativos conhecidas;
• bots e contas de suporte que são intencionalmente inativas;
• Contas de emergência ou para casos de quebra de vidro;
• contas em lista de retenção legal ou exceção de retenção;
• Usuários que recentemente alteraram o provedor de identidade ou o mapeamento de conta;
• Usuários já desativados, a menos que você esteja auditando um trabalho de limpeza anterior.

Um registro de candidato simples deve conter o ID do usuário Matrix, last_seen_tso carimbo de data/hora de criação, o indicador de administrador, o tipo de conta e o motivo pelo qual a regra de inatividade foi atendida. Manter essas evidências facilita muito as revisões e decisões de reversão posteriores.

Como saber se a seleção de candidatos é suficientemente boa?

Procure três sinais:

• Completude: seu script percorreu toda a lista de usuários locais.
• Explicabilidade: cada candidato tem uma razão visível, como "visto pela última vez há 242 dias, conta não administrativa e não de serviço".
• Baixo risco de falsos positivos: contas especiais e exceções comerciais foram filtradas antes de qualquer chamada destrutiva.

Se não for possível cumprir esses requisitos, altere o processo antes de prosseguir. Por exemplo, adicione uma etapa de aprovação humana, envie um aviso de inatividade ou comece com a suspensão em vez da desativação.

Etapa 3: Inspecione cada conta antes da desativação.

Para um usuário local específico, o Synapse documenta:

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

Exemplo:

USER_ID="@olduser:example.com"

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

A resposta pode incluir o estado administrativo da conta, indicadores de desativação e exclusão, data e hora de criação e última visualização, identidades externas e identificadores de terceiros. Este é o momento de verificar se a conta afetada é realmente a que você pretende acessar.

Você deve usar "apagar verdadeiro" ou "apagar falso"?

Use "erase": falsequando o objetivo operacional for desativar o acesso, mantendo as informações do perfil. De acordo com a documentação atual do Synapse, a desativação normal remove tokens de acesso ativos, o hash da senha, dispositivos e chaves de criptografia de ponta a ponta, pushers, IDs de terceiros, associações a salas, dados da conta, convites pendentes e informações relacionadas à validade da conta.

Use "erase": truequando sua política também exigir a remoção do nome de exibição, URL do avatar, campos de perfil personalizados e a marcação do usuário como apagado. A exclusão não significa que todos os registros históricos sejam destruídos. O Synapse documenta explicitamente que as mensagens enviadas anteriormente não são excluídas por esta API, e as mídias enviadas também não são excluídas automaticamente.

Essa distinção é crucial. Se sua política exige a exclusão de conteúdo além da simples exclusão do perfil, a desativação da conta por si só não é suficiente.

Etapa 4: Faça um teste, desative e verifique.

Antes de implementar as alterações, grave os IDs de usuário finais em um arquivo de texto simples ou JSON e revise-o. Um teste deve ser imutável durante todo o período de alterações: se o script de geração de candidatos for alterado enquanto você estiver desativando usuários, interrompa o processo e gere novamente a lista de aprovados.

Para cada usuário local aprovado, chame o endpoint de desativação documentado:

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

Exemplo sem apagar o 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"

Exemplo com apagamento 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"

Em seguida, consulte a conta novamente:

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

Um resultado operacional bem-sucedido deve ser exibido "deactivated": true. Se você solicitou a exclusão, verifique também "erased": true. Não use "a API retornou HTTP 2xx" como seu único critério de sucesso; leia o registro do usuário após a alteração.

O que a desativação realmente remove?

A documentação atual do Synapse lista vários efeitos da desativação. Entre eles estão a remoção de tokens de acesso ativos, identificadores de terceiros, dispositivos, chaves de criptografia de ponta a ponta, pushers, hashes de senha, associações a salas, convites pendentes e dados da conta. Também remove o usuário do diretório de usuários.

Com isso erase: true, o Synapse remove adicionalmente o nome de exibição, o URL do avatar, os campos de perfil personalizados e marca a conta como excluída.

A Synapse também documenta itens importantes que não são removidos por esta operação. Isso inclui mensagens enviadas e recebidas, mídias carregadas, mapeamentos de SSO, registros de data e hora de criação, alterações de limite de taxa, registros mensais de usuários ativos e algumas informações de consentimento. A lista documentada não é necessariamente exaustiva, portanto, considere a desativação como o encerramento da conta — e não como uma exclusão universal de dados.

Você também precisa excluir os arquivos de mídia enviados pelo usuário?

Se a sua política de retenção exigir a exclusão de mídias armazenadas localmente e carregadas pelo usuário, o Synapse fornece um endpoint separado:

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

Exemplo:

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

A API de mídia do usuário exclui mídias locais e miniaturas armazenadas pelo repositório de mídia do Synapse. A documentação observa duas limitações importantes para a operação. Primeiro, mídias armazenadas em um repositório externo não são afetadas por esta API. Segundo, se você não definir um limite, o endpoint exclui 100 arquivos por solicitação, portanto, usuários com um grande histórico de mídia podem precisar fazer várias chamadas.

Não adicione a exclusão automática de mídias, a menos que sua política de retenção exija isso. É um processo consideravelmente mais prejudicial do que a desativação da conta e pode afetar mídias ainda referenciadas em salas antigas.

Quando é que se deve usar a suspensão em vez da suspensão?

A Synapse também documenta uma API de suspensão de conta. A suspensão bloqueia atividades como enviar mensagens, entrar em salas, enviar convites, alterar informações de perfil e a maioria das redações, mantendo um caminho de recuperação diferente da desativação.

A suspensão é mais adequada quando você precisa de uma retenção administrativa reversível, quando a inatividade é incerta ou quando uma revisão de desligamento ainda está em andamento. A desativação é a opção mais eficaz quando o acesso deve ser encerrado e tokens, dispositivos, assinaturas de salas e dados da conta devem ser removidos.

Para limpeza automatizada, uma política em etapas costuma ser mais segura:

1. Sinalizar uma conta após o limite de inatividade;
2. notificar ou revisar;
3. suspender se a propriedade for incerta;
4. Desativar somente após o período de retenção ou aprovação ter expirado.

Como automatizar a limpeza de forma segura?

Mantenha a descoberta e a desativação como tarefas separadas. A tarefa de descoberta deve ser somente leitura e gerar um arquivo candidato. A tarefa de execução deve consumir apenas um arquivo aprovado e registrar cada solicitação e o status da resposta.

Um fluxo de trabalho com qualidade de produção também deve:

• seguir todos os tokens de paginação;
• Limitar a taxa de solicitações em lote em vez de disparar milhares simultaneamente;
• Excluir administradores de servidor e contas de serviço nomeadas por padrão;
• Armazenar registros de data e hora em UTC;
• Registre a versão da política de limpeza que foi selecionada para cada conta;
• Interromper em caso de erros de autenticação, autorização ou erros repetidos do servidor;
• Consultar novamente cada usuário após a desativação;
• Mantenha os tokens de acesso administrativo fora do código-fonte e dos registros de log.

Se a verificação pós-alteração não corresponder ao estado solicitado, não prossiga cegamente com o lote restante. Investigue as primeiras falhas e determine se o problema está relacionado a permissões, compatibilidade da versão da API, um problema de configuração de proxy, integração com o Matrix Authentication Service ou uma condição específica da conta.

Lista de verificação final

• Use um token de portador com privilégios de administrador do servidor.
• Enumere todas as páginas de usuários locais, não apenas as dos primeiros 100 usuários.
• Defina inatividade com um limite e exclusões documentados.
• Analise individualmente as contas de alto risco antes de tomar qualquer providência.
• Gere e aprove uma lista de teste.
• Use o endpoint de desativação em vez de presumir que o Synapse suporta a exclusão permanente completa da conta.
• Selecione esta opção erase: truesomente quando a exclusão do perfil fizer parte da política.
• Gerencie os arquivos de mídia carregados separadamente quando necessário.
• Verificar deactivatede, quando aplicável, erasedapós cada alteração.

A limpeza mais confiável é aquela que você pode explicar posteriormente: qual regra de inatividade selecionou uma conta, quais exceções foram verificadas, qual ação da API foi executada e qual campo pós-alteração comprovou o estado desejado. Esse padrão é mais útil do que simplesmente maximizar o número de contas processadas em uma única execução.