처음 apidog run을 실행했을 때 "액세스 토큰을 찾을 수 없습니다(No access token found)"라는 메시지와 함께 중단된다면, 아무도 경고하지 않는 명령줄 워크플로의 한 부분에 부딪힌 것입니다. 플래그, 시나리오 ID, 리포터는 모두 탭에서 쉽게 복사할 수 있습니다. 인증은 복사된 명령이 머신에서 작동하지 않거나, 로그에 비밀이 유출되거나, 랩톱에서는 조용히 작동하지만 CI에서는 오류 메시지가 설명하지 않는 이유로 실패하는 단계입니다.
이 가이드는 해당 단계에 대한 전용 답변입니다. Apidog CLI는 Apidog 앱에서 구축한 API 테스트 시나리오를 터미널에서 직접 실행하는 npm 패키지인 apidog-cli입니다. 이러한 시나리오는 사용자 계정에 저장되어 있으므로, CLI는 이를 가져와 실행할 수 있음을 증명해야 하며, 이는 액세스 토큰을 통해 이루어집니다. 토큰 처리를 한 번 올바르게 설정하면 이후의 모든 실행은 깔끔한 한 줄 명령으로 처리됩니다. 잘못 설정하면 세 가지 다른 환경에서 동일한 인증 오류와 씨름하게 될 것입니다.
액세스 토큰 생성, apidog login을 사용한 로그인, apidog whoami를 사용한 로그인 사용자 확인, 토큰 저장 위치, apidog run이 사용할 토큰을 결정하는 방법, 그리고 대부분의 팀이 파이프라인 파일에 붙여넣는 대신 CI에서 해당 토큰을 비밀로 처리하는 등 전체 표면을 다룰 것입니다. 설치 메커니즘은 별도의 가이드에 있습니다. 이 가이드는 오직 인증에 관한 것입니다. CLI를 아직 설치하지 않았다면, Apidog CLI 설치 가이드부터 시작한 다음 다시 여기로 돌아오세요.
CLI에 토큰이 필요한 이유
CLI는 자체 테스트를 수행하지 않습니다. Apidog 프로젝트에 접속하여 ID로 시나리오를 찾고 데스크톱 앱과 동일한 방식으로 실행합니다. 이러한 설계 때문에 인증이 필요합니다. 시나리오, 환경 값, 어설션은 모두 계정의 서버 측에 저장되어 있으므로 러너는 서버가 이러한 정보를 넘겨주기 전에 자신을 식별해야 합니다.
액세스 토큰은 자신을 식별하는 방법입니다. 토큰은 Apidog 계정에 연결되어 있으므로, 토큰으로 인증된 실행은 사용자가 할 수 있는 모든 것을 수행할 수 있습니다. 즉, 프로젝트를 읽고, 시나리오를 가져오고, 정의된 환경에 대해 실행합니다. 이것이 바로 토큰이 보호해야 할 자격 증명인 이유이기도 합니다. 토큰을 소유한 사람은 누구든지 사용자를 대신하여 시나리오가 대상으로 하는 환경에 대해 시나리오를 실행할 수 있습니다. 다른 서비스의 개인 액세스 토큰을 다루는 방식과 동일하게 취급하십시오.
이것은 테스트가 수행하는 인증과는 다른 종류의 인증입니다. 시나리오는 아마도 테스트 대상 엔드포인트에 자체 베어러 토큰이나 API 키를 보낼 것이며, 이는 API 인증 방법에서 다루는 별개의 문제입니다. CLI의 액세스 토큰은 러너를 Apidog에 인증합니다. 요청 내의 자격 증명은 API에 대한 요청을 인증합니다. 이 두 가지는 서로 다른 위치에 저장되고 다른 일정으로 교체되므로 혼동하지 마십시오.
1단계: 액세스 토큰 생성
토큰은 CLI가 아닌 Apidog에서 생성합니다. 토큰이 나타나는 두 가지 위치가 있으며, 어떤 것을 사용할지는 수행하는 작업에 따라 달라집니다.
여러 시나리오에서 재사용할 계정에 범위가 지정된 토큰의 경우, Apidog 앱 또는 웹 콘솔을 열고 아바타를 클릭한 다음 계정 설정에서 API 액세스 토큰 섹션을 찾으십시오.
토큰을 생성하고 즉시 복사하여 비밀번호 관리자와 같은 안전한 곳에 저장하십시오. 일반적으로 페이지를 벗어나면 전체 문자열을 다시 볼 수 없으며, 이는 자격 증명에서는 일반적인 일이며 나타나는 즉시 복사해야 하는 이유입니다.
CI에 연결할 특정 시나리오와 연결된 토큰의 경우 더 빠른 경로가 있습니다. 테스트 시나리오를 열고 CI/CD 탭으로 전환한 다음 명령줄 옵션을 선택하고 액세스 토큰 생성을 클릭하십시오. Apidog는 토큰, 시나리오 ID, 환경 ID가 이미 채워진 상태로 전체 apidog run 명령을 생성합니다. 이렇게 생성된 명령은 정식 시작점이며, 이를 복사하면 ID를 손으로 입력할 필요가 없습니다. 완벽한 Apidog CLI 가이드는 CI/CD 탭에 대해 자세히 설명합니다.
어떤 경우든 결과는 동일합니다. 즉, 토큰 문자열입니다. 다음으로 무엇을 할지는 두 가지 인증 스타일 중에서 선택하는 것입니다.
2단계: 인증 스타일 선택
CLI는 토큰을 제시하는 두 가지 방법을 지원하며, 이들은 서로 다른 상황에 적합합니다.
첫 번째는 저장된 로그인입니다. apidog login을 한 번 실행하면 CLI가 토큰을 머신에 저장하고, 이후의 모든 apidog run은 자동으로 이를 읽습니다. 그 이후에는 어떤 명령줄에도 토큰이 나타나지 않습니다. 이는 매일 사용하는 개발자 머신에 적합합니다.
두 번째는 명령별입니다. apidog run 호출 자체에 --access-token을 전달하며, 일반적으로 환경 변수에서 가져옵니다. 아무것도 저장되지 않고, 토큰은 매번 새로 제공되며, 디스크에 흔적을 남기지 않습니다. 이는 러너가 일시적이고 토큰이 비밀에서 오는 CI에 적합합니다.
아마도 로컬에서는 저장된 로그인을 사용하고 파이프라인에서는 명령별 토큰을 사용하는 두 가지 모두를 사용할 것입니다. 다음 두 섹션에서는 각각에 대해 설명합니다.
3단계: apidog login으로 로컬 로그인
자신의 머신에서는 한 번 로그인하고 토큰을 잊어버리세요. 대화형 양식은 토큰을 요청하므로 문자열이 셸 기록에 나타나지 않습니다.
apidog login
CLI는 액세스 토큰을 요청하고, 사용자가 붙여넣으면 Enter 키를 누릅니다. 내부적으로는 저장하기 전에 Apidog에 대해 토큰을 검증합니다. 유효하지 않거나 만료된 토큰은 첫 실행에서 나중에 실패하는 대신 즉시 거부됩니다. 성공하면 로그인한 계정을 확인하고 자격 증명이 저장된 위치를 알려줍니다.
예를 들어 설정 스크립트 내에서 토큰을 직접 전달하려면 --with-token 플래그를 사용하십시오.
apidog login --with-token YOUR_ACCESS_TOKEN
이 형식에 대한 한 가지 주의사항: 명령줄의 토큰은 셸 기록에 남고 명령이 실행되는 동안 프로세스 목록에서 읽을 수 있습니다. 수동 사용의 경우 대화형 apidog login을 선호하고, 제어하는 변수에서 값을 읽는 비대화형 설정의 경우 --with-token을 예약하십시오. 커밋하는 스크립트에 실제 토큰을 절대 넣지 마십시오.
토큰은 어디로 가나요? CLI는 홈 폴더의 .apidog 디렉토리 아래에 있는 구성 파일에 토큰을 기록합니다. 이는 사용자 자신의 머신에 있는 로컬 자격 증명 저장소이며, 바로 그 목적을 위한 것입니다. 토큰은 사용자 계정만 읽을 수 있는 디스크에 저장되며, CLI는 사용자가 다시 입력할 필요 없이 이후 모든 실행에서 이를 가져옵니다. 공유되거나 일시적인 머신에 있는 경우 저장된 로그인을 건너뛰고 대신 명령별 토큰을 사용하여 작업 후 아무것도 남아있지 않도록 하십시오.
4단계: apidog whoami로 확인
로그인 후, 의존하기 전에 제대로 작동하는지 확인하십시오.
apidog whoami
이것은 CLI가 현재 인증된 계정을 출력합니다. 실제 시나리오를 실행하지 않고 "로그인되어 있나, 그리고 누구로 로그인되어 있나?"라는 질문에 가장 빠르게 답하는 방법입니다. 실행이 인증 오류로 실패하고 문제가 토큰인지 아니면 하위 문제인지 확실하지 않을 때마다 사용하십시오. whoami가 사용자 계정을 표시한다면 저장된 로그인은 제대로 작동하고 있는 것이므로 다른 곳을 찾아볼 수 있습니다.
apidog whoami는 저장된 토큰이 아닌 특정 토큰을 확인하고 싶다면 --access-token도 허용합니다. 이는 파이프라인에서 신뢰하기 전에 CI 토큰이 유효한지 확인하는 데 유용합니다. 안전한 터미널에서 일회성 apidog whoami --access-token YOUR_ACCESS_TOKEN에 토큰을 붙여넣고, 어떤 계정으로 확인되는지 확인한 다음 비밀 저장소로 옮기십시오.
공유 머신에서 작업을 마치거나 다른 계정으로 전환하려는 경우, 저장된 자격 증명을 지우십시오.
apidog logout
이렇게 하면 구성 파일에서 저장된 토큰이 제거됩니다. 다음 apidog run은 새로운 로그인 또는 --access-token 플래그를 필요로 할 것이며, 이는 머신을 반납한 후 원하는 동작입니다.
5단계: apidog run이 토큰을 선택하는 방법
러너가 확인하는 순서를 이해하면 "액세스 토큰을 찾을 수 없습니다(No access token found)" 오류는 더 이상 미스터리가 아닙니다. apidog run을 호출할 때 CLI는 다음 순서로 토큰을 찾습니다.
- 명령에 전달된
--access-token플래그 (있는 경우). - 이전
apidog login에서 디스크에 저장된 토큰.
둘 중 아무것도 찾지 못하면 중지하고 먼저 login을 실행하거나 --access-token을 전달하도록 알려줍니다. 이 우선순위는 유용합니다. 플래그는 항상 저장된 로그인보다 우선하므로, 일상적으로 자신의 계정으로 로그인되어 있어도 로그아웃하지 않고 일회성 실행을 위해 다른 토큰으로 덮어쓸 수 있습니다.
실제로 이는 로컬 실행이 ID만큼 짧을 수 있음을 의미합니다.
apidog run -t 605067 -e 1629989 -n 1 -r cli
저장된 로그인이 토큰을 제공하므로 이 줄에는 토큰이 없습니다. -t는 시나리오를 ID로 지정하고, -e는 환경을 선택하며, -n 1은 한 번 실행하고, -r cli는 읽기 쉬운 보고서를 출력합니다. 아무것도 저장되지 않으므로 토큰을 명시적으로 전달하는 CI 형식과 비교해 보십시오.
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
동일한 명령, 동일한 시나리오, 다른 인증 소스. 이것이 로컬 및 CI 인증 간의 전체 차이점이며, 이 가이드의 나머지 부분은 CI 절반을 올바르게 설정하는 방법에 관한 것입니다. 이러한 실행 뒤에 있는 전체 플래그 참조는 완벽한 Apidog CLI 가이드에서 모든 옵션을 다룹니다.
6단계: CI에서 토큰을 비밀로 처리
여기서 팀들이 어려움을 겪습니다. 해결책은 한 가지 규칙입니다. 토큰은 CI 시스템의 비밀 저장소에 저장되며, 환경 변수로 명령에 도달합니다. 커밋된 파일, 저장소에 체크인된 파이프라인 정의, 빌드 로그에는 절대 나타나지 않습니다.
CI 내에서 로그인하지 마십시오. 또한 러너가 생성하는 파일에 토큰을 기록하지 마십시오. 마스크된 비밀에서 가져온 명령별 --access-token 형식을 사용하십시오. 아래의 모든 예제는 동일한 형태를 따릅니다. 즉, 플랫폼에서 한 번 이름이 지정된 비밀은 실행 단계에서 $APIDOG_ACCESS_TOKEN으로 참조됩니다.
GitHub Actions
토큰을 저장소의 설정(Settings) > 비밀 및 변수(Secrets and variables)에 저장한 다음, env를 통해 단계에 노출시키십시오.
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
GitHub는 로그에서 비밀을 자동으로 마스킹하며, env를 통해 전달하면 가시적인 명령줄에 나타나지 않습니다. 여기서 가장 흔한 실패는 이름 불일치입니다. env 키, ${{ secrets.X }} 참조, 그리고 설정에서 생성한 비밀은 모두 동일한 이름을 사용해야 합니다. 보고서 아티팩트를 포함한 전체 워크플로는 GitHub Actions의 Apidog CLI에 있습니다.
GitLab CI
APIDOG_ACCESS_TOKEN을 설정(Settings)에서 마스크되고 보호된 CI/CD 변수로 저장하고, .gitlab-ci.yml 파일에는 절대 저장하지 마십시오. 그런 다음 GitLab은 프로젝트 변수를 작업 환경에 주입하므로 직접 참조하십시오.
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
변수를 "마스크됨(masked)"으로 표시하면 GitLab에게 작업 로그에서 변수를 수정하도록 지시하고, "보호됨(protected)"으로 표시하면 보호되지 않은 브랜치에서는 사용할 수 없도록 하여 포크나 기능 브랜치에서 유출될 수 없도록 합니다.
Jenkins
토큰을 Jenkins 자격 증명으로 저장한 다음, environment 블록에 바인딩하여 출력되지 않고 변수로 사용할 수 있도록 합니다.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
}
}
}
}
Jenkins는 이렇게 바인딩된 자격 증명을 콘솔 출력에서 마스킹합니다. 이 단계를 중심으로 전체 파이프라인을 구축한다면, CI/CD 파이프라인의 Apidog CLI가 주변 구조를 다룹니다.
패턴은 모든 러너에서 동일합니다. 플랫폼의 마스크된 비밀, 명령의 환경 변수, 그리고 여기에서 읽어들이는 --access-token 플래그입니다. 이는 파이프라인의 모든 자격 증명에 적용하는 것과 동일한 원칙이며, 여러 API 키를 관리한다면 API 키 관리 모범 사례를 읽어볼 가치가 있습니다.
토큰 순환 및 해지
토큰은 영원하지 않습니다. 일정에 따라 순환하고, 유출되었을 가능성이 있는 순간 즉시 해지하십시오.
순환하려면 Apidog에서 새 토큰을 생성하고, 이를 사용하는 모든 CI 시스템에서 비밀을 업데이트한 다음, 파이프라인을 실행하여 새 토큰이 작동하는지 확인하십시오. 그런 다음 토큰을 생성했던 동일한 위치에서 이전 토큰을 해지하십시오. 로컬에서는 apidog logout을 실행한 다음 새 토큰으로 apidog login을 실행하십시오. 순서가 중요합니다. 해지하기 전에 CI를 업데이트해야 합니다. 그렇지 않으면 두 단계 사이에 빌드가 실패할 것입니다.
로그, 스크린샷, 커밋, 공유 터미널 등 토큰이 있어서는 안 될 곳에 나타나면 즉시 해지하십시오. 해지하면 토큰이 모든 곳에서 동시에 무효화되므로, 이전 값을 계속 사용하는 파이프라인은 크게 실패할 것이며, 이는 원하는 신호입니다. 실패한 빌드는 복구할 수 있지만, 공개 로그에 있는 라이브 자격 증명은 복구할 수 없습니다. 더 넓은 습관을 위해 API 키 순환 모범 사례에서 주기성을 다룹니다.
한 가지 미묘한 함정: Apidog에서 토큰을 재생성하면 이전 토큰이 무효화됩니다. 재생성하고 CI 비밀을 업데이트하는 것을 잊어버리면 YAML이 변경되지 않았음에도 불구하고 해당 파이프라인이 인증 오류로 실패하기 시작합니다. 통과하던 빌드가 갑자기 인증할 수 없게 되고 워크플로 파일을 건드리지 않았다면, 재생성된 토큰이 가장 먼저 확인해야 할 사항입니다.
인증 실패 시
인증 오류는 몇 가지 원인으로 분류됩니다. 이들을 구별하는 방법은 다음과 같습니다.
"액세스 토큰을 찾을 수 없습니다(No access token found)." CLI가 --access-token 플래그도 저장된 로그인도 찾지 못했습니다. 로컬에서는 apidog login을 실행하십시오. CI에서는 비밀이 채워져 있고 --access-token 플래그가 비밀에서 읽어오는지 확인하십시오. 비어 있는 환경 변수는 동일한 메시지를 생성합니다.
"잘못된 액세스 토큰(Invalid access token)" 또는 실행 중간에 인증 오류 발생. 토큰이 잘못되었거나, 만료되었거나, 해지되었습니다. apidog whoami를 실행하여 저장된 토큰을 확인하거나, apidog whoami --access-token YOUR_TOKEN을 실행하여 특정 토큰을 확인하십시오. 둘 다 사용자 계정으로 확인되지 않는다면, 새 토큰을 생성하고 다시 로그인하십시오.
로컬에서는 작동하지만 CI에서는 실패. 고전적인 불일치입니다. 사용자 머신에는 저장된 로그인이 있으므로 로컬 실행은 성공합니다. CI 러너에는 아무것도 저장되어 있지 않으므로 전적으로 비밀에 의존합니다. 플랫폼 설정과 명령에서 비밀 이름이 정확히 일치하는지, 그리고 붙여넣을 때 쉽게 발생할 수 있는 후행 공백이나 줄 바꿈 없이 값이 저장되었는지 확인하십시오.
특정 시나리오에서 "액세스 거부됨(Access denied)". 토큰은 유효하지만, 토큰 뒤에 있는 계정이 해당 프로젝트에 접근할 수 없습니다. 프로젝트 및 시나리오 ID를 확인하고, 토큰의 계정이 해당 프로젝트에 접근할 수 있는지 확인하십시오. 이는 인증 문제가 아니라 권한 부여 문제입니다. CLI는 자신이 누구인지 증명했지만, 서버는 해당 계정이 해당 시나리오를 실행하는 것을 허용하지 않을 뿐입니다.
토큰이 명령에 도달하지만 빌드에서 여전히 유출됩니다. 로그에서 원시 토큰을 본다면, 어딘가에서 에코하고 있는 것입니다. 종종 전체 명령이나 환경을 출력하는 디버그 라인일 수 있습니다. 마스킹하십시오. 토큰의 값이 아닌 길이를 출력하여 채워져 있는지 확인하십시오. 대부분의 CI 플랫폼은 알려진 비밀을 자동으로 수정하지만, 전체 명령을 수동으로 echo하면 이를 무력화할 수 있습니다.
더 큰 워크플로에서 인증의 역할
인증은 모든 다운스트림을 가능하게 하는 작고 일회성의 관문입니다. CLI가 자신이 누구인지 증명할 수 있게 되면, Apidog 시나리오를 실행하는 것은 단일 명령으로 이루어집니다. 편집-테스트 루프 내 로컬에서, 푸시할 때마다 CI에서, 심지어 테스트를 실행하는 AI 코딩 에이전트 내에서도 마찬가지입니다. 에이전트와 함께 작업한다면 마지막 패턴은 살펴볼 가치가 있습니다. AI 에이전트를 API 테스트에 사용하는 방법은 로그인된 CLI가 에이전트가 시나리오를 실행하고 결과를 읽는 방법을 보여주며, Apidog MCP 서버는 사양을 이러한 에이전트에 직접 연결합니다.
정신 모델은 간단합니다. apidog login으로 머신에 한 번 로그인하고, apidog whoami로 확인한 다음, 저장된 토큰이 이후 모든 실행을 처리하게 하십시오. CI에서는 로그인을 건너뛰고, 토큰을 마스크된 비밀에 보관하고, --access-token으로 명령별로 전달하십시오. 일정에 따라 순환하고, 의심스러운 경우 해지하며, 해지하기 전에 CI를 업데이트하십시오. 이것이 전체 인증 스토리이며, 이를 처리하면 CLI는 좋은 테스트 러너가 있어야 할 곳인 백그라운드로 사라집니다.
사용자는 Apidog에서 시나리오를 시각적으로 계속 작성하고, CLI는 사람이 지켜보지 않는 곳에서 이를 실행합니다. Apidog를 다운로드하여 첫 번째 시나리오를 설정한 다음, 러너를 해당 시나리오로 지정하십시오. 일단 인증되면 러너가 할 수 있는 모든 것에 대한 참조는 완벽한 Apidog CLI 가이드를 열어두십시오.