Tokens pessoais

O token pessoal é uma credencial de API que autentica como você mesmo, com as suas permissões. É a forma indicada para emprestar sua identidade a uma ferramenta ou agente de IA que vai resolver uma tarefa em seu nome — cadastrar produtos a partir de uma planilha, conciliar notas de um período, gerar um relatório — fazendo exatamente o que você faria.

Ele é diferente do token de API: aquele funciona como um usuário próprio, com permissões configuradas à parte, e serve para integrar aplicativos. O token pessoal não cria um usuário paralelo — ele age com a sua identidade e segue as suas permissões.

Você pode ter vários tokens pessoais ao mesmo tempo, cada um com sua descrição, e revogar ou renovar cada um isoladamente.

Pré-requisito de acesso

Para ver e gerenciar tokens pessoais, seu usuário precisa do direito de acesso Usuário - Gerenciar tokens pessoais. Caso o item não apareça no menu, peça a um administrador para liberar esse acesso. Veja Permissão de Acesso.

Criando um token pessoal

1. Clique no seu nome, no canto superior direito, e selecione Tokens pessoais.
2. Clique em Incluir.
3. Preencha a Descrição — use algo que identifique onde o token será usado (por exemplo, o nome do agente).
4. Escolha o Nível de acesso (veja abaixo).
5. Informe a Validade, em dias (veja Validade).
6. Clique em Salvar.

Pronto o token, copie o valor exibido (ele começa com pat_) e configure-o na ferramenta que vai usá-lo. O segredo continua disponível na tela do token, então você pode revê-lo e copiá-lo novamente quando precisar.

Nível de acesso

Cada token tem um nível de acesso, que define o que ele pode fazer na API:

• Somente leitura — o token consulta dados, mas é impedido de gravar. É o padrão, e a opção mais segura para um agente que só precisa ler informações.
• Leitura e escrita — o token consulta e também grava (criar, alterar, excluir).

Mesmo no nível Somente leitura, algumas ações que apenas leem dados — como exportar, imprimir ou gerar arquivos — continuam liberadas.

Validade

Todo token pessoal tem prazo de validade, e ele é obrigatório — essa é a principal proteção do token. Passada a validade, o token deixa de funcionar automaticamente.

O prazo máximo depende do perfil do dono:

• Usuário comum: até 90 dias.
• Usuário administrador: até 1 dia. Tokens de administradores têm alcance maior, por isso valem por menos tempo.

A coluna Expira em, na listagem, mostra a data e a hora em que cada token deixa de valer.

Usando o token na API

O token pessoal é enviado no cabeçalho Authorization, no mesmo endpoint GraphQL dos demais tokens — a diferença é o prefixo pat_ no valor:

Authorization: Bearer pat_seu_token_aqui

A partir daí, as chamadas funcionam como qualquer outra requisição à API. Veja a Visão geral da API e os Exemplos de uso da API.

Renovando e revogando

Na listagem, clique em um token para abri-lo. Ali você pode:

• Renovar — gera um segredo novo e invalida o atual imediatamente, além de reiniciar o prazo de validade. Use ao trocar a credencial de uma ferramenta ou periodicamente, por segurança. Como o token antigo para de valer na hora, lembre-se de atualizar o novo valor onde ele estiver configurado.
• Revogar — invalida o token em definitivo. Ele não pode ser reativado. Use em caso de vazamento, suspeita de uso indevido ou quando o token não for mais necessário.

A coluna Situação mostra se o token está Ativo ou Revogado, e a coluna Último uso ajuda a identificar tokens esquecidos.

Gerenciamento só pelo sistema

Criar, renovar e revogar tokens pessoais são ações exclusivas de quem está logado no Fácil123. Uma requisição feita pela API — mesmo autenticada por um token pessoal — não consegue criar, renovar ou revogar tokens. Assim, um token não estende a própria validade nem cria outros tokens: a continuidade é sempre reautorizada por você, no sistema.

Trocando de empresa

Se o usuário dono do token pessoal tem acesso a mais de uma empresa (CNPJ), toda chamada roda no contexto de uma empresa específica por vez. Para mudar esse contexto, use a mutation changeCurrentUserLicensee:

curl -X POST https://app.facil123.com.br/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pat_seu_token_aqui" \
  -d '{
    "query": "mutation { changeCurrentUserLicensee(licensee_id: 1) }"
  }'

Essa mutation retorna Void, então não inclua bloco de seleção de campos depois dela, ou a API rejeita a chamada.

A troca não é por chamada: ela muda o estado do token e vale para todas as chamadas seguintes feitas com ele, até a próxima troca. Se o mesmo token já foi usado para outra empresa antes, inclusive em uma sessão anterior, ele continua nessa empresa até você trocar de novo. Por isso, antes de operações importantes com um token que acessa mais de uma empresa, confirme em qual empresa ele está antes de seguir, em vez de assumir que é a que você espera.

Se a troca falhar com o erro "The user does not have permission to perform this action", a empresa de destino não está liberada no campo Licenciados permitidos do usuário dono do token. Não existe mutation para liberar isso pela API: é preciso liberar pela interface, como mostrado em Troca de licenciados. Depois de liberado, a mesma mutation changeCurrentUserLicensee passa a funcionar normalmente, sem precisar gerar um token novo.

Perguntas e respostas

1 - Qual a diferença entre token pessoal e token de API?
R: O token de API funciona como um usuário próprio, com permissões à parte — ideal para integrar aplicativos. O token pessoal age com a sua identidade e as suas permissões — ideal para emprestar seu acesso a um agente de IA. Veja Gerando e usando seu token de API.

2 - Posso ter mais de um token pessoal?
R: Sim. Crie quantos precisar, com descrições diferentes, e revogue ou renove cada um isoladamente.

3 - Perdi o valor do token. Preciso criar outro?
R: Não. O segredo fica sempre visível na tela do token, com botão de copiar. Abra o token na listagem para revê-lo.

4 - Por que meu token parou de funcionar?
R: Provavelmente ele expirou ou foi revogado. Confira a coluna Situação e a coluna Expira em na listagem. Para voltar a usar, renove um token ativo ou crie um novo.

5 - Posso aumentar a validade além do máximo?
R: Não. O teto é de 90 dias para usuários comuns e 1 dia para administradores, tanto na criação quanto na renovação.