Pular para o conteúdo principal
Cada requisição envia um token da API pessoal no header Authorization, com o esquema Bearer:
Uma requisição sem um token válido recebe 401. Veja cada código em Erros. O Visor CLI também pode entrar pelo navegador, sem um token da API pessoal. Veja Login do Visor CLI.

​
Tokens

  • Crie, liste e revogue tokens em Configurações > Apps Conectados.
  • Você pode ter até 10 tokens ativos ao mesmo tempo. Tokens expirados e revogados não contam.
  • O Visor mostra o token completo uma única vez, logo depois que você o cria. O Visor guarda só um resumo irreversível do segredo, então ninguém, nem o suporte do Visor, consegue mostrá-lo de novo.
  • A lista de tokens mostra um prefixo seguro, como visor_pat_abcd2345efgh6789, para você diferenciar os tokens.

​
Escopos

Cada token tem um nível de acesso, que define seus escopos: Cada operação informa o escopo que exige. Um token válido sem esse escopo recebe 403 INSUFFICIENT_SCOPE. Um token nunca ganha permissões depois de criado: quando o Visor lançar um novo tipo de acesso de escrita, crie um novo token para usá-lo.

​
Validade

Escolha 30, 90 ou 365 dias ao criar o token, ou Nunca expira. Depois que o token expira, as requisições recebem 401 TOKEN_EXPIRED. Crie um novo token e troque o valor antigo nos seus scripts.
Um token sem validade funciona até você revogá-lo. Se ele vazar, qualquer pessoa com ele lê seus dados até a revogação. Prefira uma validade e revogue os tokens que não usa mais.

​
Revogação

Revogue um token nas Configurações quando não precisar mais dele ou achar que ele vazou. A revogação vale a partir da próxima requisição, que recebe 401 TOKEN_REVOKED.

​
Login do Visor CLI

O Visor CLI entra com OAuth 2.0 (código de autorização com PKCE), sem um token da API pessoal:
  1. O CLI abre a página de autorização do Visor (/oauth/authorize) no seu navegador e espera a resposta em http://127.0.0.1:<porta>/callback.
  2. Você entra no Visor e escolhe um nível de acesso: Somente leitura (pfm:read) ou Leitura e registro de transações (pfm:read, pfm:transactions:write).
  3. O CLI troca o código em /oauth/token e envia o token de acesso como Authorization: Bearer <access_token>.
O login do CLI segue estas regras:
  • Um token de acesso expira depois de 24 horas e passa a receber 401 TOKEN_EXPIRED. O CLI então usa o refresh token, que vale por 30 dias, para pegar um novo token de acesso.
  • Cada refresh token só pode ser usado uma vez. Após a renovação, armazene juntos os novos tokens de acesso e renovação. Reutilizar o refresh token anterior retorna invalid_grant.
  • Os escopos, os códigos de erro, a verificação do plano e o limite de requisição são os mesmos de um token da API pessoal. Cada token de acesso tem o seu próprio limite.
  • O login do CLI aparece como Visor CLI em Configurações > Apps Conectados. Revogue o acesso ali para encerrar o login. A próxima requisição recebe 401 TOKEN_REVOKED, e o refresh token para de funcionar.
  • Só o Visor CLI pode usar esse login na API pessoal. Os tokens que clientes MCP como Claude ou Cursor recebem não funcionam em /v1, e os tokens do Visor CLI não funcionam no servidor MCP.
Em uma máquina sem navegador, como um servidor ou o CI, crie um token da API pessoal e passe-o para o CLI.

​
Encerrar um login do CLI

O visor auth logout pode encerrar o login no servidor com POST /oauth/revoke (RFC 7009). Envie o client_id público do CLI e o token de acesso ou de renovação desse login. Não é necessário enviar segredo do cliente, sessão do navegador ou header de autenticação.
O token_type_hint é opcional. O Visor procura nos dois tipos de token mesmo quando a indicação informa o tipo errado. A resposta é 200 OK, sem corpo, inclusive para tokens desconhecidos ou já revogados. A revogação encerra o login inteiro, incluindo os tokens anteriores e posteriores da rotação. A próxima requisição desse login a /v1 recebe 401 TOKEN_REVOKED, e a renovação retorna invalid_grant. Outros logins do CLI continuam ativos. Esse endpoint não revoga clientes MCP nem tokens da API pessoal. Um client_id ausente ou diferente retorna 401 invalid_client. Um token ausente ou malformado retorna 400 invalid_request. Os metadados do servidor OAuth informam revocation_endpoint e revocation_endpoint_auth_methods_supported: ["none"].

​
Plano e disponibilidade

A API pessoal exige um plano Pro ou Premium ativo, verificado em cada requisição.
  • Se a sua conta perder o Pro ou o Premium, as requisições recebem 403 PLAN_REQUIRED. Seus tokens continuam guardados e voltam a funcionar quando o plano voltar.