Os tokens de acesso de aplicativo permitem que serviços e scripts de terceiros interajam com sua conta do Mastodon sem expor suas credenciais de login. Esses tokens autenticam requisições à API para tarefas como publicar conteúdo, ler timelines ou gerenciar notificações a partir de ferramentas externas. Sem um token, qualquer aplicativo externo precisaria do seu e-mail e senha, o que cria um risco de segurança. Este artigo explica o que são tokens de acesso, como gerá-los nas configurações do Mastodon e como usá-los com segurança em seus próprios projetos de automação.
Principais Conclusões: Gerando e Usando Tokens de Acesso de Aplicativo no Mastodon
- Preferências > Desenvolvimento > Novo Aplicativo: Abre o formulário para registrar um novo aplicativo e gerar um token.
- Seleção de escopos durante a criação do aplicativo: Controla quais ações da API o token pode realizar, como ler, escrever ou seguir.
- Campo Token de Acesso nos detalhes do aplicativo: Exibe a string do token gerado após salvar o aplicativo.
O Que São Tokens de Acesso de Aplicativo e Por Que Você Precisa Deles
Um token de acesso de aplicativo é uma string única que identifica sua conta do Mastodon para a API do Mastodon. Quando uma ferramenta de terceiros, como um cross-poster, um framework de bot ou um script personalizado, faz uma chamada à API, ela envia esse token em vez do seu nome de usuário e senha. O servidor do Mastodon verifica o token, vê quais permissões ele possui e então permite ou nega a requisição.
O Mastodon usa o protocolo OAuth 2.0 para gerenciar esses tokens. OAuth 2.0 é um padrão da indústria para acesso delegado. Isso significa que você não precisa compartilhar sua senha do Mastodon com nenhum serviço externo. Em vez disso, você cria um token com um conjunto limitado de permissões, chamadas escopos. Os escopos definem exatamente o que o token pode fazer. Por exemplo, um token com apenas o escopo read pode visualizar sua timeline inicial, mas não pode publicar. Um token com write:statuses pode publicar novos toots, mas não pode excluí-los.
Você precisa de um token de acesso de aplicativo sempre que quiser usar um cliente não oficial do Mastodon, uma ferramenta de linha de comando ou um script de automação personalizado. A API do Mastodon usa tokens para toda requisição autenticada. Se você tentar usar a API sem um token, o servidor retorna um erro 401 Não Autorizado. Gerar um token a partir das configurações da sua conta do Mastodon é a maneira padrão de conceder acesso à API com segurança.
Passos para Criar um Token de Acesso de Aplicativo no Mastodon
Siga estes passos a partir da interface web do Mastodon. Você deve estar logado como a conta que será a proprietária do token. O token gerado atuará em nome dessa conta apenas.
- Abra o menu Preferências
Clique no seu avatar no canto superior direito da interface do Mastodon. Um menu suspenso aparece. Selecione Preferências nesse menu. - Navegue até a seção Desenvolvimento
Na barra lateral esquerda da página de Preferências, encontre o link Desenvolvimento e clique nele. Isso abre uma página que lista quaisquer aplicativos existentes que você registrou. Se você ainda não tem aplicativos, a lista está vazia. - Clique no botão Novo Aplicativo
Na página de Desenvolvimento, clique no botão Novo Aplicativo. Isso abre um formulário onde você define o nome e as permissões do aplicativo. - Insira o nome do aplicativo
Digite um nome descritivo no campo Nome do aplicativo. Use um nome que ajude você a lembrar para que serve este token, como “Cross-poster para Twitter” ou “Script de bot pessoal”. - Defina a URI de Redirecionamento
Para a maioria das tarefas de automação pessoal, insiraurn:ietf:wg:oauth:2.0:oobno campo URI de Redirecionamento. Isso instrui o fluxo OAuth a retornar o token diretamente no navegador ou na saída do script, em vez de redirecionar para uma página web. Se você estiver construindo um aplicativo web que lida com o redirecionamento, insira a URL de callback do seu aplicativo. - Selecione os escopos necessários
Role para baixo até a seção Escopos. O Mastodon agrupa os escopos em categorias: read, write, follow, push e admin. Em cada categoria, você pode selecionar sub-escopos como read:statuses ou write:media. Selecione apenas os escopos que seu aplicativo realmente precisa. Por exemplo, um bot que apenas publica atualizações de status precisa de write:statuses, mas não precisa de read ou admin. Para selecionar um escopo, marque a caixa ao lado dele. - Envie o formulário do aplicativo
Clique no botão Enviar na parte inferior do formulário. O Mastodon salva o aplicativo e redireciona você para a página de detalhes do aplicativo. - Copie o token de acesso
Na página de detalhes do aplicativo, localize o campo rotulado Seu token de acesso. Ele contém uma longa string alfanumérica. Clique no ícone de copiar ao lado dele ou selecione o texto e copie manualmente. Armazene este token em um local seguro, como um gerenciador de senhas ou um arquivo de variáveis de ambiente. Você não poderá ver o token completo novamente depois de sair desta página.
Depois de copiar o token, você pode usá-lo em qualquer cliente da API do Mastodon. Por exemplo, em um script Python usando a biblioteca Mastodon.py, você passa o token como o parâmetro access_token ao criar o objeto Mastodon. Em um comando curl, você o inclui no cabeçalho HTTP Authorization como Authorization: Bearer SEU_TOKEN_AQUI.
Erros Comuns e Considerações de Segurança
Token visível na lista de aplicativos, mas não copiado
O Mastodon exibe o token de acesso apenas uma vez, logo após você criar o aplicativo. Se você sair da página de detalhes sem copiar o token, não poderá recuperá-lo novamente. Você deve excluir o aplicativo e criar um novo para obter um token fresco. Sempre copie o token imediatamente após o envio e armazene-o em um local seguro.
Selecionar muitos escopos
Dar a um token mais escopos do que o necessário aumenta o risco se o token vazar. Um token com escopo admin pode realizar ações administrativas em sua conta, como alterar configurações ou visualizar mensagens diretas. Restrinja os escopos ao mínimo necessário. Para um script simples de apenas leitura, selecione apenas read ou read:statuses. Para um bot de postagem, selecione apenas write:statuses e write:media se você fizer upload de imagens.
Usar o token em JavaScript do lado do cliente
Não incorpore seu token de acesso em código JavaScript que é executado no navegador de um usuário. Qualquer pessoa que visualizar o código-fonte da página pode ver o token. Em vez disso, mantenha o token em um servidor que você controla e faça chamadas à API a partir do lado do servidor. Se você precisar construir um aplicativo Mastodon do lado do cliente, use o fluxo completo de código de autorização OAuth 2.0, que redireciona o usuário para o Mastodon para conceder permissão sem expor seu token.
Token usado em um repositório público do GitHub
Se você acidentalmente confirmar um token em um repositório público, revogue-o imediatamente. Vá para Preferências > Desenvolvimento, clique no nome do aplicativo e depois clique no botão Excluir. Crie um novo aplicativo com um token fresco. Para evitar isso, use variáveis de ambiente ou um arquivo de configuração que seja excluído do controle de versão via .gitignore.
Tokens de Acesso do Mastodon vs. Fluxo de Código de Autorização OAuth 2.0
| Item | Token de Acesso de Aplicativo | Fluxo de Código de Autorização OAuth 2.0 |
|---|---|---|
| Melhor para | Scripts pessoais, bots de usuário único, testes | Aplicativos web multi-usuário, aplicativos móveis, clientes de terceiros |
| Complexidade de configuração | Baixa: gerado a partir da página de Preferências | Alta: requer um servidor web para lidar com redirecionamentos e trocar códigos |
| Exposição do token | Token é estático e visível na interface | Token é trocado no servidor e nunca exposto ao usuário |
| Granularidade de escopo | Mesmo que os escopos OAuth, selecionados na criação | Mesmos escopos, mas podem ser solicitados por sessão |
| Método de revogação | Excluir o aplicativo em Preferências | Revogar o token específico via API ou configurações da conta |
Os tokens de acesso de aplicativo são uma versão simplificada do OAuth 2.0. Eles pulam a etapa de redirecionamento e fornecem um token permanente diretamente. Use-os para sua própria automação. Para aplicativos nos quais outras pessoas farão login, implemente o fluxo OAuth completo para que cada usuário se autentique com sua própria conta do Mastodon.
Agora você pode gerar um token de acesso de aplicativo em Preferências > Desenvolvimento e usá-lo em qualquer cliente da API do Mastodon. Para seu próximo projeto de automação, tente usar o token com um comando curl para buscar sua timeline inicial. Uma dica prática: armazene o token em uma variável de ambiente chamada MASTODON_ACCESS_TOKEN e faça referência a ela em seus scripts em vez de codificar a string. Isso mantém o token fora do seu código-fonte e facilita a rotação de tokens quando necessário.