La primera vez que ejecutas apidog run y se detiene con "No access token found" (No se encontró token de acceso), te encuentras con la única parte del flujo de trabajo de la línea de comandos sobre la que nadie te advierte. Los flags, los IDs de escenario, los reportes son fáciles de copiar de una pestaña. La autenticación es el paso donde un comando copiado falla en tu máquina, filtra un secreto en un log, o funciona silenciosamente en tu laptop y falla en CI por razones que el mensaje de error no explica.
Esta guía es la respuesta dedicada a ese paso. La CLI de Apidog es un paquete npm, apidog-cli, que ejecuta los escenarios de prueba de API que construyes en la aplicación Apidog directamente desde una terminal. Debido a que esos escenarios viven en tu cuenta, la CLI debe probar que tiene permiso para recuperarlos y ejecutarlos, y lo hace con un token de acceso. Maneja correctamente el token una vez y cada ejecución posterior será sencilla. Si lo haces mal, lucharás contra el mismo error de autenticación en tres entornos diferentes.
Cubriremos toda la superficie: cómo generar un token de acceso, iniciar sesión con apidog login, verificar quién eres con apidog whoami, dónde se almacena el token, cómo apidog run decide qué token usar, y la parte que la mayoría de los equipos hacen mal, manejar ese token como un secreto en CI en lugar de pegarlo en un archivo de pipeline. La mecánica de instalación se encuentra en una guía separada; esta trata solo sobre la autenticación. Si aún no has instalado la CLI, comienza con la guía de instalación de Apidog CLI, y luego regresa aquí.
Por qué la CLI necesita un token
La CLI no lleva pruebas propias. Accede a tu proyecto Apidog, encuentra un escenario por ID y lo ejecuta de la misma manera que lo haría la aplicación de escritorio. Ese diseño es la razón por la que necesita autenticarse: el escenario, los valores del entorno, las aserciones, todo vive en el servidor en tu cuenta, por lo que el ejecutor tiene que identificarse antes de que el servidor entregue cualquiera de esos datos.
Un token de acceso es cómo se identifica. El token está vinculado a tu cuenta Apidog, por lo que una ejecución autenticada con tu token puede hacer lo que tú puedes hacer: leer tus proyectos, buscar tus escenarios, ejecutarlos contra los entornos que has definido. Esa es también la razón por la que el token es una credencial que debes proteger. Cualquiera que lo tenga puede ejecutar escenarios como tú, contra cualquier entorno al que se dirijan esos escenarios. Trátalo como tratarías un token de acceso personal para cualquier otro servicio.
Este es un tipo de autenticación diferente de la autenticación que realizan tus pruebas. Tus escenarios probablemente envían sus propios tokens portadores o claves API a los puntos finales bajo prueba, y eso es una preocupación separada cubierta en métodos de autenticación de API. El token de acceso de la CLI autentica al ejecutor en Apidog. Las credenciales dentro de tus solicitudes autentican tus solicitudes en tu API. Mantén claras las dos, porque viven en lugares diferentes y rotan en diferentes programaciones.
Paso 1: genera un token de acceso
Creas el token en Apidog, no desde la CLI. Hay dos lugares donde aparece, y cuál uses depende de lo que estés haciendo.
Para un token con ámbito de tu cuenta que reutilizarás en varios escenarios, abre la aplicación Apidog o la consola web, haz clic en tu avatar y busca la sección de token de acceso API en la configuración de tu cuenta.
Genera uno, cópialo inmediatamente y guárdalo en un lugar seguro como un administrador de contraseñas. Por lo general, no podrás ver la cadena completa de nuevo después de salir de la página, lo cual es normal para las credenciales y la razón para copiarla en el momento en que aparece.
Para un token vinculado a un escenario específico que estás integrando en CI, hay un camino más rápido. Abre el escenario de prueba, cambia a su pestaña CI/CD, elige la opción de línea de comandos y haz clic para generar un token de acceso. Apidog construye todo el comando apidog run para ti con el token, el ID del escenario y el ID del entorno ya completados. Ese comando generado es el punto de partida canónico, y copiarlo significa que nunca escribirás un ID a mano. La guía completa de Apidog CLI detalla esa pestaña CI/CD.
De cualquier manera, el resultado es el mismo: una cadena de token. Lo que hagas con ella a continuación es la elección entre dos estilos de autenticación.
Paso 2: elige tu estilo de autenticación
La CLI soporta dos formas de presentar el token, y se adaptan a diferentes situaciones.
La primera es un inicio de sesión almacenado. Ejecutas apidog login una vez, la CLI guarda el token en tu máquina y cada apidog run posterior lo lee automáticamente. No hay token en la línea de comandos después de eso. Esto es lo que quieres en una máquina de desarrollo que usas todos los días.
La segunda es por comando. Pasas --access-token en la llamada a apidog run misma, generalmente desde una variable de entorno. No se almacena nada, el token se proporciona fresco cada vez y no deja rastro en el disco. Esto es lo que quieres en CI, donde el ejecutor es efímero y el token proviene de un secreto.
Probablemente usarás ambos, el inicio de sesión almacenado localmente y por comando en el pipeline. Las próximas dos secciones cubren cada uno.
Paso 3: inicia sesión localmente con apidog login
En tu propia máquina, inicia sesión una vez y olvídate del token. El formulario interactivo te lo solicita para que la cadena nunca aparezca en el historial de tu shell:
apidog login
La CLI te pide tu token de acceso, lo pegas y presionas Enter. Entre bastidores, valida el token contra Apidog antes de guardar cualquier cosa; un token inválido o caducado es rechazado al instante en lugar de fallar más tarde en tu primera ejecución. Si tiene éxito, confirma la cuenta con la que inició sesión y te indica dónde almacenó la credencial.
Si prefieres pasar el token directamente, por ejemplo, dentro de un script de configuración, usa la bandera --with-token:
apidog login --with-token TU_TOKEN_DE_ACCESO
Una precaución con esta forma: un token en la línea de comandos termina en el historial de tu shell y puede ser leído de la lista de procesos mientras el comando se ejecuta. Prefiere el apidog login interactivo para un uso manual, y reserva --with-token para una configuración no interactiva donde estés leyendo el valor de una variable que controlas. Nunca pongas un token real en un script que vayas a cometer.
¿A dónde va el token? La CLI lo escribe en un archivo de configuración bajo un directorio .apidog en tu carpeta de inicio. Ese es un almacén de credenciales local en tu propia máquina, que es precisamente el objetivo: el token se encuentra en el disco donde solo tu cuenta de usuario puede leerlo, y la CLI lo recoge en cada ejecución posterior sin que tengas que volver a escribirlo. Si estás en una máquina compartida o desechable, omite el inicio de sesión almacenado y utiliza el token por comando en su lugar, para que nada persista después de que te alejes.
Paso 4: verifica con apidog whoami
Después de iniciar sesión, confirma que funcionó antes de depender de ello:
apidog whoami
Esto imprime la cuenta con la que la CLI está autenticada actualmente. Es la forma más rápida de responder "¿estoy conectado y con qué usuario?" sin ejecutar un escenario real. Úsalo siempre que una ejecución falle con un error de autenticación y no estés seguro de si el problema es el token o algo posterior; si whoami muestra tu cuenta, el inicio de sesión almacenado está bien y puedes buscar en otro lugar.
apidog whoami también acepta --access-token si deseas verificar un token específico en lugar del almacenado. Esto es útil para confirmar que un token de CI es válido antes de confiar en él en un pipeline: pega el token en un apidog whoami --access-token TU_TOKEN_DE_ACCESO único desde una terminal segura, ve a qué cuenta resuelve, luego muévelo a tu almacén de secretos.
Cuando hayas terminado en una máquina compartida, o cuando quieras rotar a una cuenta diferente, borra la credencial almacenada:
apidog logout
Esto elimina el token guardado del archivo de configuración. El siguiente apidog run necesitará un nuevo inicio de sesión o un flag --access-token, que es el comportamiento deseado después de devolver una máquina.
Paso 5: cómo apidog run elige un token
Una vez que entiendes el orden en que el ejecutor verifica, el error "No access token found" deja de ser misterioso. Cuando llamas a apidog run, la CLI busca un token en este orden:
- La bandera
--access-tokenpasada en el comando, si está presente. - El token almacenado en disco de un
apidog loginanterior.
Si no encuentra ninguno, se detiene y te indica que ejecutes login primero o que pases --access-token. Esa precedencia es útil: una bandera siempre prevalece sobre el inicio de sesión almacenado, por lo que puedes estar conectado como tú mismo día a día y aun así anularlo con un token diferente para una ejecución única sin cerrar sesión.
En la práctica, esto significa que tus ejecuciones locales pueden ser tan cortas como los IDs:
apidog run -t 605067 -e 1629989 -n 1 -r cli
No hay token en esa línea, porque el inicio de sesión almacenado lo proporciona. La bandera -t nombra el escenario por ID, -e selecciona el entorno, -n 1 lo ejecuta una vez, y -r cli imprime un informe legible. Compáralo con el formato de CI, donde pasas el token explícitamente porque no hay nada almacenado:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
Mismo comando, mismo escenario, diferente fuente de autenticación. Esa es toda la distinción entre la autenticación local y la de CI, y el resto de esta guía trata de hacer bien la parte de CI. Para la referencia completa de los flags detrás de estas ejecuciones, la guía completa de Apidog CLI cubre cada opción.
Paso 6: maneja el token como un secreto en CI
Aquí es donde los equipos se queman. La solución es una regla: el token vive en el almacén de secretos de tu sistema de CI, y llega al comando como una variable de entorno. Nunca aparece en un archivo comprometido, una definición de pipeline verificada en el repositorio o un registro de construcción.
No inicies sesión dentro de CI, y no escribas el token en un archivo que el ejecutor cree. Usa la forma --access-token por comando, alimentada desde un secreto enmascarado. Cada ejemplo a continuación sigue la misma forma: el secreto nombrado una vez en la plataforma, referenciado como $APIDOG_ACCESS_TOKEN en el paso de ejecución.
GitHub Actions
Guarda el token en la configuración del repositorio, en Secrets and variables (Secretos y variables), luego exponlo al paso a través de env:
- name: Ejecutar escenario de prueba 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 }}
GitHub enmascara automáticamente el secreto en los registros, y pasarlo a través de env lo mantiene fuera de la línea de comandos visible. El error más común aquí es una falta de coincidencia de nombres: la clave env, la referencia ${{ secrets.X }} y el secreto que creaste en Configuración deben usar el mismo nombre. El flujo de trabajo completo, incluidos los artefactos de informe, se encuentra en Apidog CLI en GitHub Actions.
GitLab CI
Almacena APIDOG_ACCESS_TOKEN como una variable CI/CD enmascarada y protegida en la Configuración, nunca en el archivo .gitlab-ci.yml. Luego, referénciala directamente, ya que GitLab inyecta variables de proyecto en el entorno del trabajo:
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 la variable como "masked" (enmascarada) le indica a GitLab que la oculte de los registros de trabajos; marcarla como "protected" (protegida) la mantiene fuera de las ramas desprotegidas, para que una bifurcación o una rama de características no puedan exfiltrarla.
Jenkins
Almacena el token como una credencial de Jenkins, luego vincúlalo en el bloque environment para que esté disponible como variable sin que nunca se imprima:
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('Pruebas de API') {
steps {
sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
}
}
}
}
Jenkins enmascara las credenciales vinculadas de esta manera en la salida de la consola. Si construyes el pipeline completo alrededor de este paso, Apidog CLI en un pipeline CI/CD cubre la estructura circundante.
El patrón es idéntico en todos los ejecutores: un secreto enmascarado en la plataforma, una variable de entorno en el comando y el flag --access-token que lee de ella. Esa es la misma disciplina que aplicarías a cualquier credencial en un pipeline, y vale la pena leer las mejores prácticas de gestión de claves API si gestionas más de una.
Rotación y revocación de tokens
Los tokens no son para siempre. Rótatelos según un cronograma y revócalos en el momento en que uno pueda haberse filtrado.
Para rotar, genera un token nuevo en Apidog, actualiza el secreto en cada sistema de CI que lo use y ejecuta un pipeline para confirmar que el nuevo funciona. Luego, revoca el token antiguo desde el mismo lugar donde lo creaste. Localmente, ejecuta apidog logout seguido de apidog login con el nuevo token. El orden importa: actualiza CI antes de revocar, o fallarás una compilación entre los dos pasos.
Revoca inmediatamente si un token aparece donde no debería, un registro, una captura de pantalla, un commit, una terminal compartida. La revocación invalida el token en todas partes a la vez, por lo que cualquier pipeline que aún use el valor antiguo fallará ruidosamente, que es la señal que deseas. Una compilación fallida es recuperable; una credencial activa en un registro público no lo es. Para el hábito más amplio, las mejores prácticas de rotación de claves API cubren la cadencia.
Una trampa sutil: regenerar un token en Apidog invalida el anterior. Si regeneras y olvidas actualizar un secreto de CI, ese pipeline comenzará a fallar con un error de autenticación, aunque nada haya cambiado en el YAML. Cuando una compilación que solía pasar de repente no puede autenticarse y no tocaste el archivo de flujo de trabajo, un token regenerado es lo primero que debes verificar.
Cuando falla la autenticación
Los errores de autenticación se agrupan en algunas causas. Así es como se distinguen.
“No access token found” (No se encontró token de acceso). La CLI no encontró ni un flag --access-token ni un inicio de sesión almacenado. Localmente, ejecuta apidog login. En CI, confirma que el secreto esté poblado y que el flag --access-token lo esté leyendo; una variable de entorno vacía produce este mismo mensaje.
“Invalid access token” (Token de acceso inválido) o un error de autenticación a mitad de la ejecución. El token es incorrecto, caducado o revocado. Ejecuta apidog whoami para verificar el token almacenado, o apidog whoami --access-token TU_TOKEN para verificar uno específico. Si ninguno se resuelve a tu cuenta, genera un nuevo token e inicia sesión de nuevo.
Funciona localmente, falla en CI. El clásico desajuste. Tu máquina tiene un inicio de sesión almacenado, por lo que las ejecuciones locales tienen éxito; el ejecutor de CI no tiene nada almacenado y depende completamente del secreto. Confirma que el nombre del secreto coincide exactamente en la configuración de la plataforma y el comando, y que el valor se guardó sin un espacio o nueva línea final, lo cual es fácil de introducir al pegar.
“Access denied” (Acceso denegado) en un escenario específico. El token es válido, pero la cuenta detrás de él no puede acceder a ese proyecto. Verifica los ID del proyecto y del escenario, y confirma que la cuenta del token tiene acceso a ese proyecto. Esto es un problema de autorización, no de autenticación; la CLI demostró quién es, el servidor simplemente no permitirá que esa cuenta ejecute ese escenario.
El token llega al comando pero la compilación sigue filtrándolo. Si alguna vez ves el token sin procesar en un registro, lo estás imprimiendo en algún lugar, a menudo una línea de depuración que imprime el comando completo o el entorno. Enmascáralo: imprime la longitud del token para confirmar que está poblado, nunca su valor. La mayoría de las plataformas de CI redactan automáticamente los secretos conocidos, pero un echo manual del comando completo puede anularlo.
Cómo encaja la autenticación en el flujo de trabajo general
La autenticación es la pequeña puerta de una sola vez que hace posible todo lo que viene después. Una vez que la CLI puede demostrar quién es, ejecutar un escenario de Apidog se convierte en un solo comando, localmente dentro de tu ciclo de edición y prueba, en CI en cada push, e incluso dentro de un agente de codificación de IA que ejecuta tus pruebas por ti. Ese último patrón merece un vistazo si trabajas con agentes: cómo usar agentes de IA para pruebas de API muestra cómo una CLI con sesión iniciada permite a un agente ejecutar tus escenarios y leer el resultado, y el servidor Apidog MCP conecta tus especificaciones con esos agentes directamente.
El modelo mental es simple. Inicia sesión una vez en tu máquina con apidog login, verifica con apidog whoami, y deja que el token almacenado se encargue de cada ejecución posterior. En CI, omite el inicio de sesión, guarda el token en un secreto enmascarado y pásalo por comando con --access-token. Rota los tokens periódicamente, revoca si hay sospechas y actualiza CI antes de revocar. Esa es toda la historia de la autenticación, y una vez manejada, la CLI se desvanece en segundo plano, donde pertenece un buen ejecutor de pruebas.
Sigues creando escenarios visualmente en Apidog, y la CLI los ejecuta donde ningún humano está observando. Descarga Apidog para configurar tu primer escenario, luego apunta el ejecutor hacia él. Para todo lo que el ejecutor puede hacer una vez autenticado, la guía completa de Apidog CLI es la referencia que debes tener abierta.