KapsuleHost는 두 가지 개발자 인터페이스를 제공합니다. 계정을 프로그래밍 방식으로 읽기 위한 범위가 지정된 API 키와 사용자 머신 및 CI 러너에서 Turborepo 및 Nx 빌드를 가속화하는 원격 빌드 캐시입니다.
둘 다 기본적으로 활성화되지 않습니다. 둘 다 설정에서 생성되며, 둘 다 비밀을 정확히 한 번 제공합니다.
API 키 생성
API 키는 설정, 보안, API 키 카드 아래에 있습니다.
- 설정으로 이동한 다음 보안을 선택합니다.
- API 키로 스크롤한 후 새 키를 클릭합니다.
- 키에 이름을 지정합니다. 필드에 "키 이름 (예: 내 자동화 스크립트)"라고 제안합니다. 이름은 사용자 참조용이므로 키가 사용될 위치를 명시하도록 작성합니다.
- 범위 칩을 클릭하여 키가 수행할 수 있는 작업을 선택합니다. 3개의 읽기 범위가 미리 선택됩니다:
read:sites,read:email,read:domains. 칩을 클릭하여 추가하거나 제거합니다. - 생성을 클릭합니다.
전체 키는 "지금 복사"라는 제목의 녹색 패널에 한 번만 나타납니다. 이를 곧바로 비밀 저장소에 복사합니다. 해당 패널을 닫으면 키는 사라지고 짧은 접두사만 유지되며, 이것이 목록에서 다시 표시될 수 있는 전부입니다.
키는 두 번째로 표시되지 않으며 복구할 수 없습니다. 키를 잃어버렸다면 해당 키를 취소하고 새 키를 생성합니다. 공유 문서, 티켓, 커밋 또는 채팅 메시지에 붙여넣지 않습니다.
소유자 및 관리자 역할만 키를 생성할 수 있습니다. 다른 역할은 권한 오류를 받습니다. 키가 생성되면 보안 경고 이메일이 해당 키를 생성한 사람의 주소로 전송되므로 예상치 못한 경우 즉시 조사할 가치가 있습니다.
범위
7가지 범위가 제공됩니다:
| 범위 | 권한 |
|---|---|
read:sites | 웹사이트 읽기 |
write:sites | 웹사이트에 대한 쓰기 작업을 위해 예약됨 |
read:email | 사서함 읽기 |
write:email | 사서함에 대한 쓰기 작업을 위해 예약됨 |
read:domains | 도메인 읽기 |
write:domains | 도메인에 대한 쓰기 작업을 위해 예약됨 |
read:billing | 청구 데이터 읽기를 위해 예약됨 |
고객 API는 현재 읽기 전용입니다. write: 범위 및 read:billing은 키에서 선택할 수 있지만 현재 고객 엔드포인트가 사용하지 않으므로 이들을 부여해도 아무것도 변경되지 않습니다. 실제로 필요한 읽기 범위만 부여하고 쓰기 엔드포인트가 출시되면 키를 다시 확인합니다.
키 사용
Authorization 헤더에서 키를 베어러 토큰으로 보냅니다.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
3개의 엔드포인트가 고객 API 키를 허용합니다:
| 엔드포인트 | 필요한 범위 | 반환 |
|---|---|---|
GET /api/v1/sites | read:sites | 도메인, 애플리케이션 유형 및 상태가 포함된 웹사이트 |
GET /api/v1/domains | read:domains | 상태 및 만료일이 포함된 도메인 |
GET /api/v1/mailboxes | read:email | 사서함 |
키가 없거나 알 수 없거나 취소된 키를 사용한 요청은 401를 반환합니다. 올바른 범위가 없는 유효한 키는 필요한 범위를 명시하는 메시지와 함께 403을 반환합니다. 성공한 모든 호출은 키의 마지막 사용 타임스탬프를 업데이트합니다.
천천히 폴링합니다. 이러한 엔드포인트는 라이브 계정 데이터를 읽으며, 대량의 루프는 악용과 구별되지 않습니다. 대시보드가 필요로 하는 항목의 경우 1분에 한 번이 충분하고, 보통 1시간에 한 번이면 충분합니다.
키 검토 및 취소
API 키 테이블은 각 활성 키를 이름, 접두사 (키의 표시 시작) 및 범위로 나열합니다. 행 끝의 취소를 클릭하여 비활성화합니다.
취소는 즉시 적용되며 확인 대화가 없습니다. 해당 키를 사용한 다음 요청은 401을 사용하여 실패합니다. 취소된 키는 복구할 수 없으므로 클릭하기 전에 이를 사용하는 항목을 파악해야 합니다.
키는 이를 생성한 사람이 아니라 계정에 속합니다. 팀 페이지에서 팀원을 제거해도 해당 팀원이 생성한 키는 취소되지 않습니다. 오프보딩에 키 검토를 포함시킵니다. 사람을 제거한 다음 여기로 돌아와 그들이 생성한 항목을 모두 취소합니다.
키 생성 및 취소는 모두 감사 로그에서 api_key.* 작업 아래 행위자 및 원래 IP 주소와 함께 기록됩니다.
원격 빌드 캐시
설정 레일의 고급 그룹에 있는 개발자 페이지는 원격 빌드 캐시를 제공합니다. 패널은 이를 "Turborepo 및 Nx 빌드를 가속화하여 머신 및 CI 파이프라인 전체에서 분산 캐시를 공유하는 방법"으로 설명합니다.
- 설정으로 이동한 다음 개발자를 선택합니다.
- 원격 캐시 활성화를 클릭합니다.
- "새 토큰이 생성되었습니다. 지금 복사하세요. 다시는 표시되지 않습니다"라는 제목의 패널에서 토큰을 복사합니다.
그런 다음 CI 구성 또는 로컬 .env.local에서 두 가지 환경 변수를 설정합니다:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
팀 ID는 동일한 페이지의 설정 지침에 표시된 KapsuleHost 계정 ID입니다.
이 페이지는 자신의 호환성을 명시합니다: Turborepo 1.x 이상, Nx 16 이상, 동일한 원격 캐시 프로토콜을 구현하는 모든 도구입니다. 아티팩트는 계정별로 저장되며 절대 계정 전체에서 공유되지 않습니다.
카드에는 두 가지 추가 컨트롤이 있습니다:
- 토큰 회전은 새 토큰을 발급하고 이전 토큰을 무효화합니다. 이전 토큰을 보유한 모든 CI 작업이 캐시 사용을 중지하므로 토큰을 회전하고 비밀을 함께 업데이트합니다.
- 비활성화는 캐시를 완전히 끕니다.
둘 중 하나 선택
이들은 서로 관련 없는 문제를 해결하며 서로 교환할 수 없습니다.
KapsuleHost 외부의 항목이 계정 상태를 알아야 할 때 API 키를 사용합니다. 사이트를 나열하는 상태 보드, 도메인 만료가 임박했다는 경고를 표시하는 스크립트, 인벤토리 내보내기입니다.
모든 머신 및 모든 CI 실행이 동일한 변경되지 않은 패키지를 다시 빌드하기 때문에 빌드가 느릴 때 원격 빌드 캐시를 사용합니다. 호스팅된 사이트와 관련이 없으며 계정 데이터를 읽지 않습니다.
문제 해결
모든 요청이 401을 반환합니다. 헤더를 Authorization: Bearer <key>로 단일 공백으로 보냈는지, 키를 복사할 때 잘리지 않았는지, 취소되지 않았는지 확인합니다. 키의 시작 부분을 접두사 열과 비교하여 사용 중인 키가 맞는지 확인합니다.
요청이 범위를 명시하는 403을 반환합니다. 키에 해당 범위가 없습니다. 범위는 키가 생성될 때 고정되므로 올바른 범위를 사용하여 대체 키를 생성하고 이전 키를 취소합니다.
API 키 카드를 볼 수 없습니다. 개발자 페이지가 아니라 보안 페이지에 있습니다. 개발자 페이지는 빌드 캐시만 보유합니다.
새 키 버튼이 아무것도 하지 않습니다. 역할이 관리자 이하입니다. 소유자 또는 관리자에게 문의합니다.
빌드가 캐시에 도달하지 않습니다. TURBO_TOKEN 및 TURBO_TEAM이 모두 빌드 환경에 있는지, 토큰을 설정한 이후로 회전하지 않았는지, 페이지에 여전히 활성 배지가 표시되는지 확인합니다.
내가 생성하지 않은 키가 나타났습니다. 이를 손상으로 취급합니다. 취소한 다음 계정 보안을 확인하고 감사 로그에서 변경된 다른 항목을 확인합니다.