API 키
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
API 키는 역할 기반 액세스 제어(RBAC)를 사용합니다. 키에는 조직 전체 역할, 앱 범위 바인딩 또는 둘 다를 설정할 수 있습니다. 모든 앱 바인딩은 해당 앱을 소유한 조직에 계속 연결됩니다. 최소 권한 원칙을 따르려면 조직 전체 역할을 할당하는 대신 선택한 앱으로 키를 제한하세요.
API 키는 어디에서 관리하나요?
“API 키는 어디에서 관리하나요?” 섹션다음으로 이동: 설정 > 조직 > API 키 로 console.capgo.app/settings/organization/api-keys.
페이지에는 두 개의 섹션이 표시됩니다:
- RBAC 키 — 역할이 할당된 키(권장). 이 키들은 새로운 역할 기반 권한 시스템을 사용합니다.
- 레거시 키 — 단순 모드 기반 시스템(
read,upload,write,all)을 역할 할당 없이 사용하는 구형 키.

새 API 키를 생성하는 방법
섹션 제목: “새 API 키를 만드는 방법”-
Members 섹션에서 ”+” RBAC 키 테이블 상단의 버튼.
-
다음을 입력하세요 키 정보:
- 이름 (필수) — 키를 설명하는 라벨(예: “CI/CD Deploy” 또는 “Monitoring Read-Only”).
- 보안 키 생성 (선택) — 체크하면 서버에서 키가 해시됩니다. 평문 키는 한 번만 생성 후 표시되며, 이후에는 다시 확인할 수 없습니다.
- 만료일 설정 (선택) — 키가 더 이상 작동하지 않을 날짜를 선택하세요. 일부 조직은 정책으로 만료를 필수로 적용합니다.

-
키 범위를 선택하세요:
- 조직 전체 접근 권한 — 선택하세요 조직 역할 조직 전체의 기본 권한을 정의합니다. 사용 가능한 역할은 본인의 역할 수준에 따라 달라집니다:
- 없음 — 조직 전체 접근 권한 없음.
- 멤버 — 조직에 대한 기본 읽기 권한.
- 관리자 — 조직 및 모든 앱에 대한 전체 관리 권한.
- 앱 전용 접근 — 활성화 이 키를 선택한 앱으로 제한. 각 앱 바인딩은 해당 앱의 소유 조직에 연결된 상태로 유지되며, 이 모드에서는 조직 전체 RBAC 역할만 생략됩니다.
- 조직 전체 접근 권한 — 선택하세요 조직 역할 조직 전체의 기본 권한을 정의합니다. 사용 가능한 역할은 본인의 역할 수준에 따라 달라집니다:
-
키가 공개 API를 통해 조직을 생성해야 하는 경우, 다음을 활성화하세요. 조직 생성 허용.
이로 인해 전역
org.create권한이 추가됩니다. 키에는 조직 범위org_admin또는org_super_admin바인딩입니다. 대시보드에서 선택하면 관리자 생성되는org_admin바인딩입니다. 이 키가 새 조직을 생성하면 Capgo가 해당 새 조직의 Super Admin으로 이 키를 자동 지정합니다. -
앱 액세스를 부여하려면:
- 시기 이 키를 선택한 앱으로 제한 이 활성화되어 있으면, 아래에서 조직을 선택하세요 앱을 필터링할 조직 해당 앱이 표시됩니다. 선택된 앱 바인딩은 소유 조직과 계속 연결되며, 이 필터는 조직 전체 액세스를 부여하지 않습니다.
- 클릭 “+ 앱 추가”, 하나 이상의 앱을 선택한 다음 각 앱에 역할을 지정하세요:
- 앱 조회자 — 앱에 대한 읽기 전용 권한.
- 앱 업로더 — 새 bundle을 upload할 수 있습니다.
- 앱 개발자 — bundle upload, 디바이스 관리, native build 트리거, channel 설정 변경이 가능합니다.
- 앱 관리자 — 앱에 대한 모든 권한.
- 앱 미리보기 — CI/CD 라이프사이클 미리보기: bundle을 upload하고 preview channel을 생성합니다. 이 channel은 이 key에 한해서만 channel 범위의 라이프사이클 권한을 자동으로 받습니다.
-
클릭 “생성”.
-
체크했다면 보안 키 생성, 모달에 평문 키가 표시됩니다. 즉시 복사하세요 — 모달을 닫으면 다시 확인할 수 없습니다.

프리뷰 워크플로우에는 App Preview 키를 사용하세요
“미리보기 워크플로우를 위해 App Preview 키 사용” 섹션사용 앱 미리보기 임시 비공개 미리보기 채널을 만들고 번들을 업로드해 프로모션한 뒤 채널과 번들을 모두 삭제하는 CI용입니다. 기존 기본 또는 메인 채널에는 라이프사이클 액세스 권한이 없습니다.
- RBAC 키를 생성하고 활성화 이 키를 선택한 앱으로 제한.
- 아래 앱을 필터링할 조직, 조직을 선택하면 해당 조직의 앱이 표시됩니다. 선택한 각 앱은 소유 조직과 연결된 상태를 유지합니다.
- 프리뷰 배포에 사용할 앱만 추가하세요.
- 선택 앱 미리보기 선택한 각 앱에 대해.
- 보안 키를 생성하고, 적절한 경우 만료일을 설정한 후 CI 시크릿 매니저에 저장하세요.
이 선택한 앱 전용 모드는 조직 전체 역할을 생략합니다. 이 모드는 하지 마세요 조직 연결을 제거하지 않습니다. 각 app_preview 바인딩은 선택한 앱과 해당 앱을 소유한 조직 범위에 그대로 유지됩니다.
| 권한 부여 | 권한 및 범위 |
|---|---|
app_preview 선택한 앱에 대한 | app.read, app.read_bundles, app.upload_bundle, 그리고 app.create_channel. |
자동 channel_preview 바인딩 | 이 키로 채널을 생성하면 Capgo가 해당 키에 자동으로 channel.read, channel.promote_bundle, 그리고 channel.delete 해당 채널에만 권한을 부여합니다. |
app_preview 유지합니다 app.read, 따라서 이 키는 선택한 앱에서 채널 메타데이터를 열거할 수 있습니다. 자동 하위 바인딩은 관리 경계: 키가 생성하지 않은 채널에 대한 라이프사이클 변경 권한을 부여하지 않습니다.
Capgo는 어떤 App Preview 키가 번들을 업로드했는지도 기록합니다. 키는 자신이 생성한 각 프리뷰 채널에 자신의 번들만 설정하고, 해당 쌍을 함께 정리할 수 있습니다. 기존 default 또는 main 채널, 다른 프리뷰 키가 생성한 채널, 또는 다른 키의 번들에 대한 채널 바인딩을 받지 않습니다.
일반적인 CI 작업에서는 풀 리퀘스트마다 고유한 채널 이름을 사용하세요:
APP_ID="com.example.app"PREVIEW_CHANNEL="pr-123"BUNDLE_VERSION="1.2.3-pr.123"
npx @capgo/cli@latest bundle upload "$APP_ID" \ --apikey "$CAPGO_API_KEY" \ --path ./dist \ --channel "$PREVIEW_CHANNEL" \ --bundle "$BUNDLE_VERSION"
npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \ --apikey "$CAPGO_API_KEY" \ --delete-bundle \ --success-if-not-found새 채널의 경우, bundle upload --channel 채널을 생성하고, 번들을 업로드한 뒤, 하나의 흐름에서 프로모션합니다. 마지막 명령은 범위가 좁은 원자적 정리 라우트를 사용합니다: 키가 프리뷰 채널과 그에 연결된 비공유 번들을 모두 소유할 때만 성공합니다. 앱 미리보기 여전히 일반적인 bundle.delete권한이 없으므로, 임의의 번들을 삭제할 수 없습니다.
참고하세요: 예제 앱의 액세스 제어 레퍼런스 전체 제한 범위를 확인하려면.
API 키를 관리(편집)하는 방법은 무엇인가요?
“API 키를 관리(편집)하는 방법은 무엇인가요?” 섹션Members 섹션에서 렌치 아이콘 목록에 있는 RBAC 키에서 (관리)를 클릭하세요. 키 상세 페이지가 열리며 다음 작업을 수행할 수 있습니다:
- 키 변경 이름.
- 다음 파일을 업데이트하세요: 조직 역할.
- 활성화 또는 비활성화 조직 생성 허용 키에 Admin 조직 역할이 있는 경우.
- 추가, 삭제 또는 변경 앱별 역할.
클릭 “변경 사항 저장” 완료되면.

API 키를 재생성하려면 어떻게 하나요?
“API 키 재생성 방법” 섹션API 키의 시크릿 값을 재생성하려면 목록의 해당 키에서 새로고침 아이콘 (재생성)을 클릭하세요.
확인 다이얼로그가 표시됩니다. 확인 후:
- 대상: 보안(해시) 키: 새 평문 키가 생성되어 모달에 한 번만 표시됩니다. 즉시 복사하세요.
- 대상: 평문 키: 키 값이 서버 측에서 재생성됩니다.
이전 키 값을 사용하는 모든 연동은 즉시 작동을 멈춥니다.

API 키를 삭제하려면 어떻게 하나요?
“API 키를 삭제하려면 어떻게 하나요?” 섹션Members 섹션에서 휴지통 아이콘 목록의 아무 키에서나 (Delete)를 클릭합니다. 대화 상자에서 삭제를 확인합니다.
키가 즉시 무효화되어 해당 키를 사용하는 모든 요청이 실패합니다.

레거시 키
“Legacy keys” 섹션해당 섹션에 키가 보이면 레거시 키 (역할 할당이 없는 키)는 이전 모드 기반 권한 시스템을 사용합니다(read, upload, write, all). 여전히 작동하지만 RBAC의 세분화된 권한을 활용할 수는 없습니다.
Legacy 키는 목록에서 재생성하거나 삭제할 수 있지만, RBAC 역할을 추가하도록 편집할 수는 없습니다. 가능하면 새 RBAC 키를 만들고 legacy 키를 삭제하는 것이 좋습니다.
legacy 키를 직접 관리해야 한다면 여전히 다음 경로에서 접근할 수 있습니다 console.capgo.app/dashboard/apikeys. 이 페이지는 deprecated 상태이며 향후 업데이트에서 제거될 예정입니다.
API 키에서 계속하기
“API Keys에서 계속하기” 섹션사용 중이라면 API 키 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 구현 세부 사항은 API 키에서 기기 구현 세부 사항은 기기에서, 그리고 번들 Bundles의 구현 세부 사항은