Kapsule Orbit API 토큰 및 REST API

API 토큰을 사용하면 스크립트, CI 파이프라인 또는 자체 도구로 브라우저 세션 없이 Kapsule Orbit을 제어할 수 있습니다. 배포를 트리거하고, CI 검사 결과를 보고하고, 빌드 아티팩트를 다운로드하고, cron 작업을 관리하는 등 모든 작업을 직접 범위를 지정한 Bearer 토큰으로 인증하여 수행할 수 있습니다.

토큰이 저장되는 위치

Orbit을 열고 최상위 네비게이션에서 Tokens을 선택합니다. 페이지 제목은 API Access Tokens이며 규칙을 명확히 표시합니다: 토큰은 생성 시점에 한 번만 표시됩니다.

전체 엔드포인트 문서는 한 번의 클릭으로 접근할 수 있습니다. API Reference 카드에는 View docs 버튼이 있으며, 이를 클릭하면 모든 Orbit 엔드포인트에 대한 패널 내 참조 문서가 열립니다.

토큰 생성

1. New token을 클릭합니다.
2. Token name을 입력합니다. 토큰을 사용할 대상(예: CI 워크플로우)을 기준으로 이름을 지으면 나중에 목록을 읽기 쉽습니다.
3. Scopes를 선택합니다.
4. 필요에 따라 Expiry를 설정합니다. 만료되지 않는 토큰의 경우 비워둡니다.
5. Create token을 클릭합니다.

원본 토큰은 One-time reveal 제목 아래에 한 번만 표시되며 복사 버튼이 있습니다. 이를 CI 보안 저장소에 직접 붙여넣으세요. 다시 확인할 방법이 없습니다. 토큰의 SHA-256 해시만 저장되므로 KapsuleHost도 이를 복구할 수 없습니다.

한 계정은 최대 20개의 활성 토큰을 보유할 수 있습니다. 21번째 토큰을 생성하려고 하면 기존 토큰을 먼저 취소하도록 요청하는 메시지가 표시됩니다.

Scopes

Scope는 토큰의 핵심입니다: 각 토큰은 부여한 권한만 가집니다.

새로운 토큰의 기본값은 deploy:write과 project:read이며, 이는 배포 파이프라인이 필요로 하는 것뿐입니다.

작업에 필요한 최소한의 scope만 부여하세요. CI 결과만 보고하면 되는 토큰은 project:write을 필요로 하지 않습니다. 읽기 전용 모니터링 스크립트는 쓰기 scope를 필요로 하지 않습니다. 참조 문서의 각 엔드포인트는 필요한 최소 scope를 나열합니다.

토큰 사용

인증은 API 베이스 https://kapsulehost.com에 대한 Bearer 헤더입니다:

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

Tokens 페이지에는 준비된 CI/CD usage 스니펫과 GitHub Actions starter 워크플로우가 있습니다. 스타터는 .github/workflows/orbit-deploy.yml로 저장되며 두 개의 저장소 보안 암호 ORBIT_TOKEN과 ORBIT_PROJECT_ID이 필요합니다. 이들을 직접 입력하지 말고 페이지에서 복사하세요.

API가 지원하는 범위

패널 내 참조 문서는 각 영역의 파라미터와 필수 scope을 설명합니다:

• Deployments: 배포를 트리거하고, 선택적으로 지정된 브랜치에서, 선택적으로 5분에서 30일 사이의 미래 시간으로 예약하며, 최대 500자의 메모를 포함합니다. 목록 조회는 커밋, 메시지, 브랜치 및 작성자에 대한 모호한 검색을 지원하며, 브랜치, 상태 및 환경에 대한 필터와 페이지당 최대 100개 결과의 커서 페이지네이션을 제공합니다.
• Deployment checks: CI 작업 시작 시 품질 게이트를 등록한 후 완료 시 결과를 보고합니다. 실패한 required 체크는 배포를 FAILED로 이동하고 환경을 이전의 성공한 배포로 되돌립니다. 이는 자신의 테스트 스위트를 진정한 배포 게이트로 만드는 방법입니다.
• Branch protection: 자동 배포가 필수 체크를 통과하고 선택적으로 누군가 승인할 때까지 차단하는 glob 패턴 규칙입니다. 프로젝트당 최대 10개 규칙.
• Build artifacts: 성공한 배포의 컴파일된 출력에 대한 사전 서명된 다운로드 URL을 가져옵니다. URL은 15분 동안 유효합니다.
• Project transfer: 다른 계정으로의 전송을 시작, 취소 및 상태를 확인합니다. Transferring an Orbit Project를 참조하세요.
• Cron jobs: cron 작업을 나열, 생성, 업데이트, 삭제, 트리거 및 실행 기록을 읽습니다. Orbit Cron Jobs를 참조하세요.
• Timeline annotations: 인시던트, 릴리스, 마일스톤, 메모 및 플래그 주석을 생성하고 관리합니다. Orbit Timeline Annotations를 참조하세요.
• Status page: 공개 상태 페이지 구성을 읽고 씁니다. Orbit Status Page를 참조하세요.
• Edge functions: 엣지 핸들러를 나열, 생성, 업데이트 및 배포합니다. Orbit Edge Functions를 참조하세요.

패널의 세션 인증은 Bearer 토큰과 함께 작동하므로, 브라우저에서 호출할 수 있는 엔드포인트는 일반적으로 스크립트에서도 호출할 수 있습니다.

Turbo Remote Cache

Tokens 페이지에는 Remote Build Cache 카드도 있습니다. Turborepo Remote Cache Protocol을 구현하여 모노레포가 CI 실행 및 개발자 머신 간에 빌드 캐시를 공유할 수 있습니다.

카드에서 활성화하고, 생성된 토큰을 복사하며, 계정 ID와 함께 CI 환경에 TURBO_TEAM로 설정합니다. 각각 최대 150 MB의 아티팩트가 허용됩니다. 카드는 또한 Rotate token과 Disable 옵션을 제공합니다.

모노레포의 CI가 변경되지 않은 패키지를 재구축하는 데 대부분의 시간을 소비한다면, 이것이 페이지에서 가장 가치가 높은 단일 기능입니다.

토큰 목록 관리

Token inventory는 모든 활성 토큰을 다음과 함께 나열합니다:

• Created 시점.
• Last used 시점, 또는 Never.
• Expires 시점, 만료 후 expired 배지 포함.

Last used 열을 감시해야 합니다. 사용되지 않은 토큰은 잘못 구성되었거나 잊혀진 것이며, 어느 쪽이든 아무것도 하지 않는 자격 증명이 남아있습니다. 페이지의 힌트 자체가 명확하게 말합니다: 인식하지 못하는 모든 것을 취소하세요.

토큰 취소

행의 취소 컨트롤을 클릭합니다. 확인은 명시적입니다: 해당 토큰으로 인증하는 모든 것이 즉시 액세스 권한을 잃으며, 이를 실행 취소할 수 없습니다.

파이프라인이 중단되었을 때, CI 보안 암호에 접근할 수 있는 누군가가 떠날 때, 또는 토큰이 유출되었다고 의심되는 순간에 취소하세요. 부분 취소나 유예 기간은 없으며, 이는 유출의 경우 정확히 원하는 방식입니다.

문제 해결

401 Unauthorized: 헤더가 잘못되었거나 토큰이 취소되었거나 만료되었습니다. 헤더가 Authorization: Bearer <token>이고 단일 공백이 있으며, CI 보안 암호에 줄바꿈이 없는지 확인하세요.

403 Forbidden: 토큰은 유효하지만 해당 엔드포인트의 scope이 부족합니다. 참조 문서는 엔드포인트당 최소 scope을 나열합니다. Scope는 생성 시 고정되므로, 올바른 scope 집합으로 새 토큰을 생성하세요.

429 on creation: 20개 토큰 제한에 도달했습니다. 목록에서 뭔가 취소하세요.

아티팩트 URL이 작동을 멈춤: 사전 서명된 URL은 15분 지속됩니다. URL을 저장하지 말고 새로운 것을 요청하세요.

예약된 배포가 거부됨: 예약된 시간은 미래의 5분에서 30일 사이여야 합니다.

다음 단계

• Deploying Your Project: 트리거된 배포가 실제로 수행하는 작업.
• Orbit Deployment Pipeline: API 배포가 만날 게이트 확인.
• Orbit Plan Limits: 플랜에 포함된 내용.