API 토큰
CI·스크립트에서 쓸 ntro_ 토큰을 만들고, 안전하게 쓰고, 철회합니다.
API 토큰은 사람이 브라우저에서 로그인할 수 없는 CI나 스크립트에서 쓰는 오래가는 열쇠입니다. ntro_로 시작하며, 토큰을 만든 사용자의 권한으로 동작합니다.
토큰 만들기
콘솔의 API 토큰 화면에서 토큰 만들기를 누르세요. 이름과 만료 기간(만료 없음, 또는 1~365일)을 정합니다.
토큰 문자열은 만들 때 한 번만 보여 줍니다
창을 닫으면 다시 볼 수 없습니다. 바로 CI의 비밀 저장소(GitHub Actions Secrets 등)에 넣어 두세요. 잃어버렸다면 철회하고 새로 만드세요.
CI에서 쓰기
토큰을 NITROSHIP_TOKEN 환경 변수로 넘기면 CLI가 알아서 사용합니다.
export NITROSHIP_TOKEN='ntro_...'
ntro whoami
ntro deploy ./dist --app my-app --prod- run: ntro deploy . --app my-app --prod
env:
NITROSHIP_TOKEN: ${{ secrets.NITROSHIP_TOKEN }}--token ntro_... 플래그로도 넘길 수 있지만, 명령줄 인자는 프로세스 목록이나 셸 기록에 남을 수 있습니다. 자동화에서는 비밀 저장소에서 환경 변수로 넣는 방식을 쓰세요.
- 토큰은 만든 사용자의 팀 역할 안에서만 동작합니다. 예를 들어
viewer팀에는 배포할 수 없습니다. - 앱 생성·배포 같은 변경 작업에는 이메일 인증이 끝난 계정이어야 합니다.
토큰 철회
필요 없어진 토큰이나 유출이 의심되는 토큰은 콘솔의 API 토큰 목록에서 바로 삭제하세요. 삭제한 토큰은 더 이상 쓸 수 없습니다. 다만 아래 설명처럼, 이미 발급된 접속 토큰은 최대 5분까지 더 쓰일 수 있습니다.
동작 방식 (참고)
API 토큰은 API로 직접 보내지 않습니다. CLI가 먼저 API 토큰으로 5분짜리 접속 토큰을 받고, 실제 API 요청에는 이 접속 토큰만 씁니다.
- 받은 접속 토큰은 만료될 때까지 재사용합니다. API가
401을 돌려주면 토큰을 다시 받아 그 요청을 한 번만 재시도합니다. - 접속 토큰을 받을 때마다 API 토큰의 만료·철회 여부와 사용자 정지 여부를 확인하고, 마지막 사용 시각을 기록합니다.
- 철회한 API 토큰으로는 더 이상 접속 토큰을 받을 수 없지만, 이미 받은 접속 토큰은 5분이 지날 때까지 쓸 수 있습니다.
CLI 없이 REST API를 직접 호출한다면 ntro token으로 접속 토큰을 받아 쓰세요. 자세한 방법은 API 인증에 있습니다.
API로 토큰 관리
콘솔 대신 API로도 관리할 수 있습니다. 이때는 로그인으로 받은 접속 토큰이 필요합니다. API 토큰이나 그것을 바꿔 받은 접속 토큰으로는 다른 API 토큰을 만들거나 조회·철회할 수 없습니다.
| 요청 | 하는 일 |
|---|---|
POST /v1/identity/tokens | 토큰 생성. 본문 {"name": "...", "expiresInDays": 30} (expiresInDays는 선택, 1~365) |
GET /v1/identity/tokens | 토큰 목록. 이름·만료일 같은 정보만 있고 토큰 문자열은 없습니다. |
DELETE /v1/identity/tokens/{tokenId} | 토큰 철회 |