Token de Acesso Pessoal Moodle 5.3: Quem Cria e Como Auditar

O token de acesso pessoal Moodle chegou com o Moodle 5.3 e, de fábrica, qualquer usuário autenticado do seu AVA pode criar um: aluno, tutor, secretaria, coordenação. O Moodle 5.3.1, de 12 de novembro de 2026, passou a avisar por e-mail quando um token é criado e quando está para vencer. Este guia mostra quem deveria poder criar esses tokens, como auditar, revogar e encaixar tudo na LGPD.

TL;DR

• No Moodle 5.3, a capacidade moodle/api:createtoken vem liberada para o papel Usuário autenticado. Na prática, todo mundo que faz login pode gerar credencial de API.
• O token vale de 7 dias a 1 ano (padrão: 1 mês), aparece uma única vez e não pode ser editado depois.
• O 5.3.1 avisa o dono por e-mail quando um token é criado, lembra antes de vencer e troca o antigo erro 500 por uma resposta 401 quando o token é inválido, vencido ou revogado.
• Não existe tela de administrador listando os tokens de todos os usuários. A auditoria hoje passa pelo banco de dados.
• Regra prática: tire a capacidade do papel Usuário autenticado, libere por papel nominal e nunca apoie integração de longo prazo no token de uma pessoa.

O que é o token de acesso pessoal Moodle

Um token de acesso pessoal é uma credencial que o próprio usuário gera para que um script ou um aplicativo aja em nome dele na nova REST API do Moodle (/api/rest/v2). O caso típico de uso do token de acesso pessoal Moodle é a coordenadora que quer puxar um relatório para uma planilha, ou o desenvolvedor que testa uma automação com a própria conta.

O panorama completo de autenticação do 5.3 (servidor OAuth 2, clientes, escopos) já está no nosso guia sobre OAuth2 no Moodle 5.3. Aqui eu vou direto ao ponto que pesa para quem administra o AVA: governança.

O que você precisa saber sobre o token de acesso pessoal Moodle, conferido na documentação oficial e no código-fonte do 5.3.1:

• Onde se cria: menu do usuário > Preferências > Conta de usuário > Tokens de acesso pessoal > Criar token (o rótulo pode variar conforme o pacote de idioma).
• Campos: nome (obrigatório), descrição (opcional), validade e pelo menos um escopo.
• Exibição única: o Moodle mostra o token uma vez só. Saiu da página, não dá para ver de novo.
• Armazenamento: o banco guarda apenas um hash do token (bcrypt). Um backup vazado não entrega os tokens em texto puro.
• Prefixo fixo pat_: existe para que ferramentas de varredura de segredos reconheçam um token vazado, com a ressalva, no próprio código, de que o prefixo não é exclusivo do Moodle.
• Sem edição: nome, validade e escopos não mudam depois de criados. Venceu, cria-se outro.

O que ele não é

Ele não é o token dos web services clássicos (aquele de webservice/rest/server.php, gerenciado em Administração do site > Servidor > Web services > Gerenciar tokens). A página de REST API tokens é explícita: os dois sistemas são separados, e a opção “Habilitar web services” nem afeta os tokens novos. Desligar web services não desliga o token pessoal.

E o token de acesso pessoal não dá mais poder do que o dono já tem. Um token de aluno enxerga o que o aluno enxerga, limitado ainda pelos escopos escolhidos.

O padrão do 5.3: todo usuário autenticado pode criar token

No arquivo de capacidades do núcleo (lib/db/access.php), a moodle/api:createtoken aparece liberada para dois arquétipos: user (Usuário autenticado) e manager (Gerente). O comentário dos desenvolvedores resume a lógica: o token age só como o dono, então não carrega mais risco do que o dono já tem. Por isso a capacidade foi marcada apenas com os riscos de spam e de dados pessoais.

Vale comparar com a capacidade equivalente dos web services clássicos, a moodle/webservice:createtoken. Ela é liberada só para o Gerente e carrega cinco marcas de risco: configuração, perda de dados, spam, dados pessoais e XSS.

O raciocínio da Moodle HQ é correto do ponto de vista de escalada de privilégio. O problema que eu vejo na operação é outro: persistência. Pense no cenário mais comum de incidente em AVA, a conta comprometida por phishing ou por senha reaproveitada:

1. O invasor entra com a senha do aluno ou do tutor.
2. Em dois cliques, cria um token de acesso pessoal Moodle de 1 ano.
3. Mesmo depois que você descobre o acesso indevido, aquela credencial independente da senha continua no banco.

A documentação oficial não diz se a troca de senha invalida os tokens pessoais. Na dúvida, no nosso procedimento de incidente a revogação é sempre um passo explícito, nunca uma consequência presumida.

O risco cresce com o papel. Um tutor ou uma secretaria com permissões amplas pode escolher escopos do tipo “qualquer usuário” (por exemplo, ver qualquer conta de usuário), e aí o script roda num notebook pessoal com acesso aos dados de centenas de alunos.

Quem deveria poder criar token: política por perfil

A resposta curta sobre quem deve criar token de acesso pessoal no seu AVA: quase ninguém por padrão, e algumas pessoas por decisão nominal. A tabela abaixo é a política que aplicamos como ponto de partida nos ambientes que administramos. Ajuste ao seu caso.

Perfil	Precisa de token pessoal?	Recomendação	Validade sugerida
Aluno	Quase nunca	Remover a capacidade	Não se aplica
Professor ou tutor	Raramente	Liberar sob pedido, por papel nominal	Até 1 mês
Secretaria ou coordenação	Às vezes (relatórios, planilhas)	Papel nominal, com justificativa registrada	1 a 3 meses
Equipe de TI	Sim, para testes	Papel nominal; integração de produção vai para outro mecanismo	7 dias a 1 mês
Administrador do site	Sim, com cautela	Evitar escopos amplos e validade longa	7 dias

Como aplicar a política no Moodle

1. Rode antes a consulta de auditoria (mais abaixo) para saber quem já tem token ativo. Mudar a regra às cegas pode quebrar um relatório que alguém usa toda segunda-feira.
2. Em Administração do site > Usuários > Permissões > Definir papéis, edite o papel Usuário autenticado e deixe moodle/api:createtoken como Não definido. Prefira isso a “Proibir”: a proibição vence qualquer permissão concedida em outro papel e impediria a liberação nominal.
3. Revise também o papel Gerente, que recebe a capacidade por arquétipo.
4. Crie um papel de sistema, por exemplo “Criador de token de API”, com apenas essa capacidade em Permitir.
5. Atribua esse papel a pessoas específicas em Administração do site > Usuários > Permissões > Atribuir papéis de sistema e registre o motivo.

Quando não fazer isso agora: se o seu AVA ainda está no 5.2 ou anterior, não há o que restringir. E se você já tem um sistema externo apoiado em tokens pessoais, migre essa integração primeiro, senão a mudança de permissão vira incidente de produção.

Um detalhe importante: a documentação não afirma que remover a capacidade invalida cada token de acesso pessoal Moodle já criado. Trate as duas coisas como etapas separadas, restringir a criação e revisar o que já existe.

Prazo de validade: qual escolher e o que o 5.3.1 avisa

O formulário de criação do token de acesso pessoal oferece cinco prazos: 7 dias, 1 mês (o padrão), 2 meses, 3 meses ou 1 ano. No código, 1 ano é o teto (MAX_LIFETIME), com um comentário que eu assino embaixo: um token sem limite é um token que ninguém revoga.

Na lista de tokens, um ícone de alerta aparece quando faltam 3 dias para o vencimento. A partir do 5.3.1 (ticket MDL-89442), o dono também recebe e-mail e notificação no sino. Os lembretes são calculados a partir de 30, 7 e 1 dia antes do vencimento, mas só disparam na segunda metade da vida do token:

Validade escolhida	Lembretes que o dono recebe
7 dias	1 dia antes
1 mês	7 dias e 1 dia antes
2 meses, 3 meses ou 1 ano	30, 7 e 1 dia antes

Depois do vencimento, sai um aviso de “token expirado”, uma única vez e só até 7 dias após a data. Esse lembrete é uma preferência de notificação comum, ligada por padrão, e o usuário pode desligar.

Como escolher o prazo

• Teste ou tarefa pontual: 7 dias. O lembrete chega na véspera e o token some sozinho.
• Relatório recorrente de uma pessoa: 1 mês, renovado conscientemente. Renovar é criar outro token e revogar o anterior.
• 1 ano: quase sempre é sinal de que aquilo deveria ser uma integração com usuário técnico ou cliente OAuth, não um token pessoal.

A armadilha clássica: o analista cria um token de 1 ano para um script, sai da empresa seis meses depois e a conta dele continua ativa. O script segue funcionando com a identidade de alguém que não trabalha mais ali. Desligamento de pessoa precisa incluir a revisão de cada token de acesso pessoal Moodle que ela criou.

O que mudou no Moodle 5.3.1

O 5.3.1 saiu em 12 de novembro de 2026, segundo as notas oficiais da versão. Para quem cuida de governança de API, cinco itens importam:

• MDL-89760, aviso de criação. Quando um token de acesso pessoal é criado, o dono recebe um e-mail. Quando um segredo de cliente OAuth 2 é criado, os administradores recebem. O e-mail é enviado direto, sem depender das preferências de mensagem, e por isso não pode ser desligado pelo usuário. A mensagem traz nome, validade e link para a página de gestão, nunca o valor da credencial. É esse aviso que denuncia o invasor que criou token na conta de alguém.
• MDL-89442, lembrete de vencimento, descrito na seção anterior.
• MDL-90024, segredo de cliente expirado. O aviso só sai se o segredo venceu sem ter sido substituído, para não incomodar quem fez a rotação certinho.
• MDL-89848, fim do erro 500. Token inválido, vencido ou revogado devolvia erro 500 (erro de servidor). Agora devolve 401 (não autorizado). Parece detalhe, mas não é: 500 dispara alerta de monitoramento como se o servidor tivesse caído, esconde o motivo real e induz integrações a ficar repetindo a chamada.
• MDL-89990, log de configuração. Ações sobre clientes OAuth 2, como a criação de segredo, passam a entrar no log de alterações de configuração.

As mesmas notas listam correções de segurança cujos detalhes só são publicados cerca de uma semana depois. Ou seja: quem está no 5.3.0 tem motivo de sobra para atualizar logo, sempre passando antes por homologação.

Como auditar tokens pessoais no seu AVA

Aqui está a lacuna que mais surpreende os gestores: não existe, no 5.3.1, uma tela de administrador com os tokens de todos os usuários. O relatório da página de tokens filtra pelo usuário logado; conferi isso no código do 5.3.1. Cada pessoa vê os próprios, e só.

A auditoria de cada token de acesso pessoal Moodle, portanto, passa pelo banco. Os tokens ficam na tabela rest_api_tokens (com o prefixo padrão, mdl_rest_api_tokens), que guarda dono, escopos, criação, validade, situação de revogação, último uso e IP do último uso. Esta consulta, para MariaDB ou MySQL, lista os tokens ativos:

SELECT u.username, u.email, u.suspended,
       t.name, t.scopes,
       FROM_UNIXTIME(t.timecreated)  AS criado_em,
       FROM_UNIXTIME(t.expirytime)   AS expira_em,
       FROM_UNIXTIME(t.lastaccessed) AS ultimo_uso,
       t.lastaccessip                AS ip_ultimo_uso
  FROM mdl_rest_api_tokens t
  JOIN mdl_user u ON u.id = t.userid
 WHERE t.revoked = 0
   AND (t.expirytime IS NULL OR t.expirytime > UNIX_TIMESTAMP())
 ORDER BY t.lastaccessed DESC;

Rode com um usuário de banco somente leitura. Se o seu prefixo de tabela não é mdl_, ajuste.

O que procurar no resultado

• Tokens de alunos. Um token de acesso pessoal em conta de aluno raramente tem justificativa.
• Validade de 1 ano ou expirytime vazio. A interface não permite token sem validade; se aparecer um, investigue a origem.
• Token nunca usado (ultimo_uso vazio). Pode ser só esquecido, ou pode ser alguém guardando acesso para depois.
• IP fora do padrão, como país diferente ou faixa de nuvem que ninguém da equipe usa.
• Escopos de “qualquer usuário” em contas que não são de TI ou administração.
• Conta suspensa (suspended = 1) com token ativo, típico de desligamento mal fechado.

Cadência recomendada: mensal, e sempre depois de um incidente ou de um desligamento sensível. Se você não tem acesso ao banco, porque o Moodle está numa hospedagem compartilhada ou num fornecedor que não abre o servidor, esse é exatamente o tipo de rotina que entra num suporte Moodle com acesso à infraestrutura.

Como revogar um token de acesso pessoal Moodle

O caminho oficial é do próprio dono: na página de tokens, Revogar corta um token ativo na hora e o tira da lista; Excluir só aparece para tokens já expirados. A revogação não tem desfazer.

Para o administrador, o 5.3.1 não traz botão para revogar o token de acesso pessoal Moodle de outro usuário. Em incidente, o recurso que usamos é marcar a revogação direto no banco, depois de backup e de testar o procedimento em homologação:

UPDATE mdl_rest_api_tokens
   SET revoked = 1
 WHERE userid = 1234
   AND revoked = 0;

O valor 1 corresponde à constante de token revogado no código, e o núcleo tem uma exceção própria para token revogado, que a partir do 5.3.1 responde 401.

Roteiro de incidente com token pessoal

1. Revogue cada token de acesso pessoal Moodle do usuário afetado.
2. Troque a senha e encerre as sessões abertas.
3. Anote ultimo_uso e o IP de cada token antes de mexer, porque isso é evidência.
4. Cruze com os logs do Moodle e do servidor web as chamadas a /api/rest/v2 no período.
5. Avalie, com o encarregado de dados, se houve acesso a dados pessoais de terceiros (próxima seção).

Quando não revogar em massa: antes de saber quais rotinas dependem daqueles tokens. Tokens com uso recente merecem uma conversa com o dono primeiro. Revogar tudo de uma vez numa sexta à tarde é a receita para o relatório da diretoria quebrar na segunda.

Se a origem do incidente for uma falha de servidor e não uma senha vazada, o roteiro é maior. Nosso checklist pós-PHP2Shell no Moodle mostra como tratar o ambiente inteiro.

Token pessoal e LGPD: credencial de acesso a dado pessoal

Um AVA guarda nome, e-mail, CPF em muitos casos, notas, frequência e, em escolas, dados de crianças e adolescentes. Um token de acesso pessoal Moodle é uma chave para parte disso. Três pontos da Lei 13.709/2018 conversam diretamente com o tema:

• Art. 46: os agentes de tratamento devem adotar medidas de segurança, técnicas e administrativas, para proteger os dados pessoais de acessos não autorizados. Deixar qualquer conta gerar credencial de API de 1 ano, sem inventário, é difícil de defender como medida adequada.
• Art. 37: controlador e operador devem manter registro das operações de tratamento. O inventário de tokens, com dono, escopo e uso, é parte desse registro.
• Art. 48: incidente que possa acarretar risco ou dano relevante aos titulares precisa ser comunicado à ANPD e aos titulares. O Regulamento de Comunicação de Incidente (Resolução CD/ANPD nº 15/2024) fixa o prazo de 3 dias úteis a partir do conhecimento do incidente.

Na prática, a governança mínima que eu recomendo cabe numa página:

1. Política escrita dizendo quem pode criar token de acesso pessoal Moodle e com qual validade máxima.
2. Inventário mensal com a consulta acima.
3. Desligamento de pessoa incluindo revisão de tokens.
4. Proibição de colar token em planilha compartilhada, repositório de código ou ferramenta de IA de terceiros.
5. Roteiro de incidente que já prevê a revogação e a avaliação de comunicação.

Um aluno com escopos “do próprio usuário” representa pouco risco para dados de terceiros. Uma secretaria com escopos “qualquer usuário” representa muito. É por isso que a política é por perfil, e não um sim ou não para o site inteiro.

Integrações: quando o token pessoal é a ferramenta errada

O token de acesso pessoal Moodle foi desenhado para o uso de uma pessoa. Integração de sistema com sistema precisa de uma identidade que não saia de férias nem peça demissão.

Cenário	Mecanismo indicado
Script de relatório de uma pessoa	Token pessoal de 7 a 30 dias
ERP, sistema acadêmico ou CRM	Cliente OAuth 2 (client credentials) ou web service clássico com usuário técnico
Aplicativo em que o usuário faz login	Cliente OAuth 2 com authorization code
Matrícula, cadastro e notas em 2026	Web services clássicos, porque a REST API nova ainda cobre poucas partes do Moodle
Aviso automático por WhatsApp (nota, prazo, matrícula)	Usuário técnico dedicado, nunca a conta de uma pessoa

No cliente OAuth 2 do 5.3, segundo a documentação de OAuth 2 clients, o access token dura 1 hora, o segredo vence em 1 ano e cada cliente pode ter até 2 segredos ativos, o que permite rotação sem parar a integração. É outra conversa de governança, e o 5.3.1 também passou a avisar quando esse segredo vence sem ter sido trocado.

Na Agathas Web, as integrações que montamos entre Moodle e a API oficial do WhatsApp, por exemplo para avisar o aluno de prazo de atividade, sempre rodam com usuário técnico próprio, papel mínimo e credencial registrada no inventário. Se quiser o mapa geral antes de decidir o mecanismo, o guia sobre como integrar Moodle com outros sistemas compara as opções.

Como a Agathas Web resolve isso

Governança de token não é um projeto grande, mas exige acesso ao banco, conhecimento de permissões do Moodle e disciplina mensal. É o tipo de tarefa que costuma ficar para depois até o dia do incidente. No nosso serviço de Moodle, ela entra assim:

• Auditoria inicial de credenciais: cada token de acesso pessoal Moodle, tokens de web service e clientes OAuth 2, com dono, escopo, validade, último uso e IP, entregue em relatório com o que revogar e o que manter.
• Política de papéis aplicada: capacidade fora do papel Usuário autenticado, papel nominal para quem precisa e validade máxima combinada com a sua equipe.
• Atualização para o 5.3.1 testada em homologação antes de ir para produção, para você receber os avisos de criação e vencimento e o fim do erro 500.
• Migração de integrações que estão penduradas em token de pessoa para usuário técnico ou cliente OAuth 2, sem parar o que está funcionando.
• Rotina mensal no SLA de sustentação: inventário, revisão de contas desligadas e roteiro de incidente alinhado à LGPD.

Como funciona a contratação: você agenda o diagnóstico gratuito de 1 hora pela página de serviços Moodle, nós olhamos o seu ambiente e saímos com proposta técnica, cronograma e investimento. A sustentação mensal parte de R$ 800 por mês, e a auditoria pode ser feita como projeto avulso.

Eu sou Cleverson Gouvêa, desenvolvedor certificado em Moodle e responsável por ambientes de EAD em produção desde a fundação da Agathas Web, em 2008. Credencial esquecida, como um token de acesso pessoal Moodle de 1 ano sem dono ativo, é um dos achados mais repetidos quando assumimos um AVA, e o 5.3 acabou de dar a todos os usuários a capacidade de criar mais uma.

Conclusão

O token de acesso pessoal Moodle é uma boa ferramenta para quem precisa automatizar algo com a própria conta. O problema está no padrão: no 5.3, todo usuário autenticado pode gerar credencial de API de até 1 ano, e não há tela de administrador para enxergar todas.

O 5.3.1 melhorou bastante a visibilidade, com aviso de criação, lembrete de vencimento e resposta 401 no lugar do erro 500. Mas a política continua sendo sua: tirar a capacidade do papel Usuário autenticado, liberar por nome, preferir validades curtas, auditar todo mês e manter integração longe do token de uma pessoa.

Se você quer essa revisão feita no seu AVA, com relatório e política aplicada, fale com a gente pelos serviços de Moodle da Agathas Web.