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