Como Autenticar a CLI do Apidog: Login, Tokens e Segredos de CI

A primeira vez que você executa apidog run e ele para com “No access token found” (Nenhum token de acesso encontrado), você atinge a única parte do fluxo de trabalho de linha de comando sobre a qual ninguém avisa. As flags, os IDs de cenário, os reportadores são todos fáceis de copiar de uma aba. A autenticação é o passo onde um comando copiado falha na sua máquina, vaza um segredo para um log, ou funciona silenciosamente no seu laptop e falha na CI por razões que a mensagem de erro não explica.

Este guia é a resposta dedicada a esse passo. A CLI do Apidog é um pacote npm, apidog-cli, que executa os cenários de teste de API que você constrói no aplicativo Apidog diretamente de um terminal. Como esses cenários residem na sua conta, a CLI precisa provar que tem permissão para buscá-los e executá-los, e faz isso com um token de acesso. Acertar o manuseio do token uma vez e cada execução posterior será uma linha única limpa. Errar e você lutará contra o mesmo erro de autenticação em três ambientes diferentes.

Abordaremos toda a superfície: geração de um token de acesso, login com apidog login, verificação de quem você está logado com apidog whoami, onde o token é armazenado, como apidog run decide qual token usar, e a parte que a maioria das equipes erra, o manuseio desse token como um segredo na CI em vez de colá-lo em um arquivo de pipeline. Os mecanismos de instalação residem em um guia separado; este é apenas sobre autenticação. Se você ainda não instalou a CLI, comece com o guia de instalação da CLI do Apidog, e depois retorne aqui.

Por que a CLI precisa de um token?

A CLI não carrega testes próprios. Ela acessa seu projeto Apidog, encontra um cenário por ID e o executa da mesma forma que o aplicativo de desktop faria. Esse design é a razão pela qual ela precisa autenticar: o cenário, os valores do ambiente, as asserções, tudo reside no lado do servidor em sua conta, então o executor precisa se identificar antes que o servidor entregue qualquer um desses itens.

Um token de acesso é como ele se identifica. O token está vinculado à sua conta Apidog, então uma execução autenticada com seu token pode fazer o que você pode fazer: ler seus projetos, buscar seus cenários, executá-los contra os ambientes que você definiu. É por isso também que o token é uma credencial que você deve proteger. Qualquer um que o possua pode executar cenários como você, contra os ambientes que esses cenários visam. Trate-o da mesma forma que você trataria um token de acesso pessoal para qualquer outro serviço.

Este é um tipo de autenticação diferente da autenticação que seus testes realizam. Seus cenários provavelmente enviam seus próprios tokens de portador ou chaves de API para os endpoints em teste, e essa é uma preocupação separada abordada em métodos de autenticação de API. O token de acesso da CLI autentica o executor no Apidog. As credenciais dentro de suas requisições autenticam suas requisições na sua API. Mantenha os dois distintos, pois eles residem em lugares diferentes e giram em cronogramas diferentes.

Passo 1: gerar um token de acesso

Você cria o token no Apidog, não na CLI. Existem dois lugares onde ele aparece, e qual você usa depende do que você está fazendo.

Para um token com escopo para sua conta que você reutilizará em vários cenários, abra o aplicativo Apidog ou o console da web, clique no seu avatar e procure na seção de configurações da sua conta a seção de token de acesso à API.

Gere um, copie-o imediatamente e armazene-o em um local seguro como um gerenciador de senhas. Você geralmente não consegue ver a string completa novamente depois de sair da página, o que é normal para credenciais e a razão para copiá-lo no momento em que aparece.

Para um token vinculado a um cenário específico que você está configurando na CI, há um caminho mais rápido. Abra o cenário de teste, vá para a aba CI/CD, escolha a opção de linha de comando e clique para gerar um token de acesso. O Apidog constrói todo o comando apidog run para você com o token, o ID do cenário e o ID do ambiente já preenchidos. Esse comando gerado é o ponto de partida canônico, e copiá-lo significa que você nunca digitará um ID manualmente. O guia completo da CLI do Apidog detalha essa aba CI/CD.

De qualquer forma, a saída é a mesma: uma string de token. O que você faz com ela em seguida é a escolha entre dois estilos de autenticação.

Passo 2: escolha seu estilo de autenticação

A CLI suporta duas maneiras de apresentar o token, e elas se adequam a diferentes situações.

A primeira é um login armazenado. Você executa apidog login uma vez, a CLI salva o token na sua máquina, e cada apidog run posterior o lê automaticamente. Nenhum token na linha de comando depois disso. Isso é o que você quer em uma máquina de desenvolvedor que você usa todos os dias.

A segunda é por comando. Você passa --access-token na própria chamada de apidog run, geralmente a partir de uma variável de ambiente. Nada é armazenado, o token é fornecido novo a cada vez, e não deixa rastros no disco. Isso é o que você quer na CI, onde o executor é efêmero e o token vem de um segredo.

Você provavelmente usará ambos, o login armazenado localmente e por comando no pipeline. As próximas duas seções cobrem cada um.

Na sua própria máquina, faça login uma vez e esqueça o token. O formulário interativo solicita que você o insira para que a string nunca apareça no seu histórico de shell:

apidog login

A CLI pede seu token de acesso, você o cola e pressiona Enter. Nos bastidores, ela valida o token contra o Apidog antes de salvar qualquer coisa; um token inválido ou expirado é rejeitado na hora, em vez de falhar mais tarde na sua primeira execução. Em caso de sucesso, ela confirma a conta com a qual fez login e informa onde a credencial foi armazenada.

Se preferir passar o token diretamente, por exemplo, dentro de um script de configuração, use a flag --with-token:

apidog login --with-token SEU_TOKEN_DE_ACESSO

Uma ressalva com este formato: um token na linha de comando vai parar no seu histórico de shell e pode ser lido da lista de processos enquanto o comando é executado. Prefira o apidog login interativo para uso manual, e reserve --with-token para configurações não interativas onde você está lendo o valor de uma variável que você controla. Nunca coloque um token real em um script que você commita.

Onde o token é armazenado? A CLI o escreve em um arquivo de configuração dentro de um diretório .apidog na sua pasta de usuário. Esse é um armazenamento de credenciais local na sua própria máquina, que é exatamente o objetivo: o token fica no disco onde apenas sua conta de usuário pode lê-lo, e a CLI o pega em cada execução posterior sem que você precise digitá-lo novamente. Se você estiver em uma máquina compartilhada ou descartável, ignore o login armazenado e use o token por comando, para que nada persista depois que você sair.

Passo 4: verifique com apidog whoami

Após o login, confirme que funcionou antes de depender disso:

apidog whoami

Isso imprime a conta com a qual a CLI está autenticada atualmente. É a maneira mais rápida de responder “estou logado, e como quem?” sem executar um cenário real. Use-o sempre que uma execução falhar com um erro de autenticação e você não tiver certeza se o problema é o token ou algo a jusante; se whoami mostrar sua conta, o login armazenado está funcionando e você pode procurar em outro lugar.

apidog whoami também aceita --access-token se você quiser verificar um token específico em vez do armazenado. Isso é útil para confirmar se um token de CI é válido antes de confiar nele em um pipeline: cole o token em um apidog whoami --access-token SEU_TOKEN_DE_ACESSO único em um terminal seguro, veja a qual conta ele se resolve, e então mova-o para seu armazenamento de segredos.

Quando terminar em uma máquina compartilhada, ou quando quiser mudar para uma conta diferente, limpe a credencial armazenada:

apidog logout

Isso remove o token salvo do arquivo de configuração. A próxima execução de apidog run precisará de um novo login ou de uma flag --access-token, que é o comportamento desejado após devolver uma máquina.

Passo 5: como apidog run escolhe um token

Depois que você entender a ordem que o executor verifica, o erro “No access token found” (Nenhum token de acesso encontrado) deixa de ser misterioso. Quando você chama apidog run, a CLI procura por um token nesta ordem:

A flag --access-token passada no comando, se presente.
O token armazenado em disco de um apidog login anterior.

Se não encontrar nenhum dos dois, ele para e informa para você executar login primeiro ou passar --access-token. Essa precedência é útil: uma flag sempre prevalece sobre o login armazenado, então você pode estar logado como você mesmo no dia a dia e ainda assim substituir por um token diferente para uma execução única sem fazer logout.

Na prática, isso significa que suas execuções locais podem ser tão curtas quanto os IDs:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Nenhum token nessa linha, porque o login armazenado o fornece. O -t nomeia o cenário por ID, -e seleciona o ambiente, -n 1 o executa uma vez, e -r cli imprime um relatório legível. Compare isso com o formato da CI, onde você passa o token explicitamente porque nada é armazenado:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

Mesmo comando, mesmo cenário, fonte de autenticação diferente. Essa é toda a distinção entre autenticação local e da CI, e o restante deste guia é sobre como acertar a parte da CI. Para a referência completa das flags por trás dessas execuções, o guia completo da CLI do Apidog cobre todas as opções.

Passo 6: trate o token como um segredo na CI

É aqui que as equipes se queimam. A correção é uma regra: o token reside no armazenamento de segredos do seu sistema de CI, e chega ao comando como uma variável de ambiente. Ele nunca aparece em um arquivo commitado, em uma definição de pipeline verificada no repositório, ou em um log de build.

Não faça login dentro da CI, e não escreva o token em um arquivo que o executor cria. Use o formato --access-token por comando, alimentado por um segredo mascarado. Cada exemplo abaixo segue o mesmo formato, o segredo nomeado uma vez na plataforma, referenciado como $APIDOG_ACCESS_TOKEN na etapa de execução.

GitHub Actions

Armazene o token nas Configurações do repositório, em Segredos e variáveis, e então exponha-o à etapa através de env:

- name: Executar cenário de teste de API
  run: |
    apidog run \
      --access-token "$APIDOG_ACCESS_TOKEN" \
      -t 605067 \
      -e 1629989 \
      -r junit,cli
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

O GitHub mascara o segredo nos logs automaticamente, e passá-lo via env o mantém fora da linha de comando visível. A falha mais comum aqui é uma incompatibilidade de nome: a chave env, a referência ${{ secrets.X }}, e o segredo que você criou nas Configurações, todos precisam usar o mesmo nome. O fluxo de trabalho completo, incluindo artefatos de relatório, reside em A CLI do Apidog no GitHub Actions.

GitLab CI

Armazene APIDOG_ACCESS_TOKEN como uma variável de CI/CD mascarada e protegida em Configurações, nunca no arquivo .gitlab-ci.yml. Em seguida, referencie-o diretamente, já que o GitLab injeta variáveis de projeto no ambiente do job:

api-tests:
  stage: test
  image: node:20
  script:
    - npm install -g apidog-cli
    - apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

Marcar a variável como “masked” (mascarada) informa ao GitLab para ocultá-la dos logs de job; marcá-la como “protected” (protegida) a mantém fora de branches desprotegidas, para que um fork ou uma branch de recurso não possa exfiltrá-la.

Jenkins

Armazene o token como uma credencial Jenkins, então vincule-o no bloco environment para que ele esteja disponível como uma variável sem nunca ser impresso:

pipeline {
  agent any
  environment {
    APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
  }
  stages {
    stage('Testes de API') {
      steps {
        sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
      }
    }
  }
}

O Jenkins mascara as credenciais vinculadas desta forma na saída do console. Se você construir o pipeline completo em torno desta etapa, a CLI do Apidog em um pipeline de CI/CD cobre a estrutura circundante.

O padrão é idêntico em todos os executores: um segredo mascarado na plataforma, uma variável de ambiente no comando, e a flag --access-token lendo a partir dele. Essa é a mesma disciplina que você aplicaria a qualquer credencial em um pipeline, e vale a pena ler as melhores práticas de gerenciamento de chaves de API se você gerencia mais de uma.

Rotação e revogação de tokens

Tokens não são para sempre. Gire-os em um cronograma e revogue-os no momento em que um possa ter vazado.

Para girar, gere um novo token no Apidog, atualize o segredo em cada sistema de CI que o utiliza e execute um pipeline para confirmar que o novo funciona. Então revogue o token antigo do mesmo lugar onde você o criou. Localmente, execute apidog logout seguido por apidog login com o novo token. A ordem importa: atualize a CI antes de revogar, ou você falhará uma build entre as duas etapas.

Revogue imediatamente se um token aparecer onde não deveria, em um log, uma captura de tela, um commit, um terminal compartilhado. A revogação invalida o token em todos os lugares de uma vez, então qualquer pipeline que ainda usa o valor antigo falhará ruidosamente, que é o sinal que você deseja. Uma build falha é recuperável; uma credencial ativa em um log público não é. Para o hábito mais amplo, as melhores práticas de rotação de chaves de API cobrem a cadência.

Uma armadilha sutil: regenerar um token no Apidog invalida o anterior. Se você regenerar e esquecer de atualizar um segredo da CI, esse pipeline começará a falhar com um erro de autenticação, mesmo que nada no YAML tenha mudado. Quando uma build que costumava passar de repente não consegue autenticar e você não mexeu no arquivo de fluxo de trabalho, um token regenerado é a primeira coisa a verificar.

Quando a autenticação falha

Erros de autenticação se agrupam em algumas causas. Veja como distingui-los.

“No access token found.” (Nenhum token de acesso encontrado) A CLI não encontrou nem uma flag --access-token nem um login armazenado. Localmente, execute apidog login. Na CI, confirme que o segredo está preenchido e que a flag --access-token está lendo a partir dele; uma variável de ambiente vazia produzirá a mesma mensagem.

“Invalid access token” (Token de acesso inválido) ou um erro de autenticação no meio da execução. O token está errado, expirado ou revogado. Execute apidog whoami para verificar o token armazenado, ou apidog whoami --access-token SEU_TOKEN para verificar um específico. Se nenhum se resolver à sua conta, gere um novo token e faça login novamente.

Funciona localmente, falha na CI. A incompatibilidade clássica. Sua máquina tem um login armazenado, então as execuções locais são bem-sucedidas; o executor da CI não tem nada armazenado e depende inteiramente do segredo. Confirme que o nome do segredo corresponde exatamente entre a configuração da plataforma e o comando, e que o valor foi salvo sem um espaço em branco no final ou uma nova linha, o que é fácil de introduzir ao colar.

“Access denied” (Acesso negado) em um cenário específico. O token é válido, mas a conta por trás dele não consegue acessar esse projeto. Verifique os IDs do projeto e do cenário, e confirme se a conta do token tem acesso a esse projeto. Este é um problema de autorização, não de autenticação; a CLI provou quem ela é, o servidor simplesmente não permitirá que essa conta execute esse cenário.

O token chega ao comando, mas a build ainda o vaza. Se você vir o token bruto em um log, você o está ecoando em algum lugar, muitas vezes uma linha de depuração que imprime o comando completo ou o ambiente. Mascare-o: imprima o comprimento do token para confirmar que ele está preenchido, nunca seu valor. A maioria das plataformas de CI redige segredos conhecidos automaticamente, mas um echo manual de todo o comando pode anular isso.

Onde a autenticação se encaixa no fluxo de trabalho maior

A autenticação é o pequeno portão, de uso único, que torna tudo a jusante possível. Uma vez que a CLI pode provar quem ela é, executar um cenário Apidog torna-se um único comando, localmente dentro do seu loop de edição-teste, na CI a cada push, e até mesmo dentro de um agente de codificação de IA que executa seus testes para você. Esse último padrão merece uma olhada se você trabalha com agentes: como usar agentes de IA para teste de API mostra como uma CLI logada permite que um agente execute seus cenários e leia o resultado, e o servidor Apidog MCP conecta suas especificações diretamente a esses agentes.

O modelo mental é simples. Faça login uma vez em sua máquina com apidog login, verifique com apidog whoami, e deixe o token armazenado carregar cada execução posterior. Na CI, pule o login, mantenha o token em um segredo mascarado e passe-o por comando com --access-token. Gire em um cronograma, revogue sob suspeita e atualize a CI antes de revogar. Essa é toda a história da autenticação, e com ela resolvida a CLI desaparece em segundo plano, onde um bom executor de testes pertence.

Você continua criando cenários visualmente no Apidog, e a CLI os executa onde nenhum humano está observando. Baixe o Apidog para configurar seu primeiro cenário e, em seguida, aponte o executor para ele. Para tudo o que o executor pode fazer uma vez autenticado, o guia completo da CLI do Apidog é a referência para manter aberta.

botão