Tokens de API

O token de API é necessário quando quem acessa /api/v1 não é um navegador, mas um script, CI, serviço externo ou outra automação. Ele substitui a sessão do navegador nas requisições de API e atua em nome do usuário que o emitiu.

O token não cria uma função separada nem concede permissões especiais. Se o usuário tem acesso à organização, a requisição de API com seu token obtém o mesmo acesso; se não tem acesso, o token não o adicionará.

O que o token oferece

O token pessoal fornece acesso bearer a rotas protegidas /api/v1. Ele é transmitido no cabeçalho HTTP:

Authorization: Bearer <token>

Em seguida, a requisição passa pelas mesmas verificações que um usuário comum na interface: associação à organização, função e permissões para a ação específica. Por isso, o token é conveniente para scripts, integrações e exportações regulares, mas deve ser armazenado como uma senha.

Na versão atual, os tokens não são configurados por escopos individuais. Cada token emitido atua com acesso total do proprietário dentro de seus direitos reais. Se você precisar de um agente de IA externo com escopos limitados, use uma conexão MCP em vez de um token de API pessoal.

Como emitir

Abra seu perfil dentro da organização e vá para a seção Tokens de API. Dê um nome compreensível: por exemplo, o nome do script, serviço ou ambiente onde o token será usado.

O prazo de validade é opcional. Se não for especificado, o token será válido até a revogação manual. Se um prazo for definido, após essa data o token deixará de conceder acesso e desaparecerá da lista de ativos.

Após a emissão, o segredo completo é exibido apenas uma vez. Copie-o imediatamente e salve-o em um armazenamento seguro. Posteriormente, a plataforma mostrará apenas o nome, a data de criação, o prazo de validade e a hora do último uso; o texto completo do token não pode ser recuperado.

Como usar com segurança

Crie um token separado para cada script ou serviço. Dessa forma, pelo nome na lista fica claro onde ele é usado, e você pode revogá-lo sem interromper outras integrações.

Não insira o token em código público, documentação, tarefas, chats ou JavaScript do lado do cliente. Para integrações do lado do servidor, armazene-o em variáveis de ambiente ou em um gerenciador de segredos.

Se o token pode ter ido parar em lugar errado, revogue-o e emita um novo. A revogação tem efeito imediato: o cabeçalho bearer antigo deixa de passar na autenticação.

Lista e revogação

Na página de Tokens de API, são exibidos apenas os tokens ativos do usuário atual. Na lista, são visíveis o nome, a data de criação, o prazo de validade e o último uso. Tokens de outras pessoas não são exibidos aqui.

Para encerrar o acesso, clique em Revogar no token desejado e confirme a ação. Isso exclui apenas aquele token; a conta do usuário e os demais tokens permanecem no lugar.

Um token expirado não precisa ser revogado manualmente para segurança de acesso: ele já não funciona. Mas, para uma nova integração, é necessário emitir um novo token e substituir o segredo no serviço que faz as requisições de API.