API 키

API 키는 역할 기반 액세스 제어(RBAC)를 사용합니다. 키에는 조직 전체 역할, 앱 범위 바인딩 또는 두 가지 모두를 설정할 수 있습니다. 모든 앱 바인딩은 해당 앱을 소유한 조직에 계속 연결됩니다. 최소 권한 원칙을 준수하려면 조직 전체 역할을 할당하는 대신 키를 특정 앱으로 제한하세요.

API 키는 어디에서 관리하나요?

이동: 설정 > Organization > API Keys 로 console.capgo.app/settings/organization/api-keys.

페이지는 다음 두 섹션으로 구성됩니다:

• RBAC 키 — 역할(role)이 할당된 키(권장). 새로운 역할 기반 권한 시스템을 사용합니다.
• 이전 API 키 — 역할 할당 없이 기존의 단순 모드 기반 시스템을 사용하는read, upload, write, all구형 키입니다.

새로운 API key를 생성하는 방법은?

1. Members 섹션에서 ”+” RBAC 키 테이블 상단의 버튼.

2. 다음 항목을 입력하세요: 키 정보:

   • 이름 (필수) — 키를 식별할 수 있는 설명 레이블 (예: “CI/CD Deploy” 또는 “Monitoring Read-Only”).
   • 보안 키 생성 (선택 사항) — 체크 시 키가 서버 측에서 해싱됩니다. 평문 키는 생성 직후 단 한 번만 표시되며 이후에는 다시 확인할 수 없습니다.
   • 만료일 설정 (선택 사항) — 키가 만료되는 날짜를 지정합니다. 일부 조직에서는 정책에 따라 만료일을 필수로 설정할 수 있습니다.

3. 키 범위를 선택하세요:

   • 조직 전체 액세스 권한 — 다음 중 하나를 선택하여 조직 역할 조직 전체의 기본 권한을 정의합니다. 사용 가능한 역할은 현재 사용자의 권한 수준에 따라 달라집니다:
     • 없음 — 조직 전체 액세스 권한 없음.
     • 멤버 — 조직에 대한 기본 읽기 권한.
     • Admin — 조직 및 모든 앱에 대한 전체 관리자 권한을 가집니다.
   • 앱 전용 액세스 — 활성화 이 키를 선택한 앱으로 제한. 각 앱 바인딩은 해당 앱의 소유 조직에 계속 연결됩니다. 이 모드에서는 조직 전체 RBAC 역할만 제외됩니다.

4. 키를 통해 공개 API에서 조직을 생성해야 하는 경우, 활성화하세요. 조직 생성 허용.

   이 기능은 글로벌 org.create 권한을 추가합니다. 또한 이 키에는 조직 범위의 org_admin 또는 org_super_admin 바인딩이 필요합니다. 대시보드에서 Admin 를 생성합니다. org_admin 바인딩을 생성합니다. 이 키로 새 조직을 생성하면, Capgo이 해당 새 조직의 Super Admin 권한을 이 키에 자동으로 부여합니다.

5. 앱 액세스 권한을 부여하려면:

   • 시기 이 키의 액세스 범위를 선택한 앱으로 제한 가 활성화된 경우, 아래에서 조직을 선택하세요. 앱 필터링을 위한 조직 를 선택하면 해당 조직의 앱이 표시됩니다. 선택된 앱 바인딩은 소유 조직과 계속 연결되어 있으며, 이 필터가 조직 전체에 대한 액세스 권한을 부여하지는 않습니다.
   • 클릭 ”+ 앱 추가”에서 하나 이상의 앱을 선택한 다음, 각 앱에 역할을 할당하세요:
     • App Reader — 앱에 대한 읽기 전용 권한
     • 앱 업로더 — 새 bundle 업로드 가능
     • 앱 개발자 — bundle 업로드, 디바이스 관리, Native Build 실행 및 channel 설정 관리 가능
     • 앱 관리자 — 앱에 대한 모든 권한
     • 앱 미리보기 — CI/CD 라이프사이클 미리보기: bundle을 업로드하고 preview channel을 생성합니다. 해당 channel은 이 키에 대해서만 자동화된 channel 범위의 라이프사이클 권한을 가집니다.

6. 클릭 “생성”.

7. 체크했다면 보안 키 생성, 모달에 평문 키가 표시됩니다. 즉시 복사하세요 — 모달을 닫으면 다시 확인할 수 없습니다.

미리보기 워크플로우에는 App Preview 키를 사용하세요

사용 앱 미리보기 임시 비공개 미리보기 채널을 생성하고, 번들을 upload 및 프로모션한 뒤, 채널과 번들을 모두 삭제하는 CI용 키입니다. 기존의 기본 또는 메인 채널에 대한 라이프사이클 액세스 권한은 없습니다.

1. RBAC 키 생성 및 활성화 이 키를 특정 앱으로 제한.
2. 아래 앱 필터링을 위한 조직, 조직을 선택하여 앱 목록을 확인하세요. 선택된 각 앱은 해당 소유 조직과 연결된 상태를 유지합니다.
3. 프리뷰 배포에 사용되는 앱만 추가하세요.
4. 선택 앱 미리보기 선택된 각 앱에 대해.
5. 보안 키를 생성하고, 필요한 경우 만료일을 설정한 뒤 CI secret manager에 저장하세요.

이 '선택된 앱 전용' 모드는 조직 전체 권한을 제외하며, 하지 마세요 조직 연결을 해제합니다. 각 app_preview binding은 선택된 앱 및 해당 앱의 소유 조직 범위 내로 제한됩니다.

권한 부여	권한 및 범위
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 따라서 이 키는 선택한 앱 내의 채널 메타데이터를 열거할 수 있습니다. 자동 자식 바인딩은 관리 boundary: 해당 키가 생성하지 않은 채널에 대해서는 lifecycle mutation 권한을 부여하지 않습니다.

Capgo는 어떤 App Preview 키가 번들을 upload했는지도 기록합니다. 해당 키는 자신이 생성한 각 preview channel에 대해 자신의 번들만 설정할 수 있으며, 해당 쌍을 함께 정리할 수 있습니다. 기존의 default 또는 main channel, 다른 preview 키가 생성한 channel, 또는 다른 키의 번들에 대해서는 channel binding을 받지 않습니다.

일반적인 CI 작업의 경우, pull request마다 고유한 channel 이름을 사용하세요:

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

새 channel의 경우, bundle upload --channel channel을 생성하고, 번들을 upload하며, 이를 promotion하는 과정을 하나의 흐름으로 처리합니다. 마지막 명령은 제한적인 atomic cleanup route를 사용합니다. 즉, 해당 키가 preview channel과 공유되지 않은 연결된 번들을 소유하고 있을 때만 성공합니다. 앱 미리보기 여전히 일반적인 bundle.delete 권한이 없으므로, 임의의 번들을 삭제할 수 없습니다.

주의

새로운 비공개 pr-<number> 채널을 사용하세요. 다음 항목을 --default, --self-assign전달하거나, 롤아웃 옵션을 --delete-linked-bundle-on-upload 이 워크플로우에 포함하지 마세요. An 앱 미리보기 키는 기존의 기본/메인 채널, 다른 프리뷰 키의 채널 또는 다른 키의 번들을 승격, 삭제 또는 변경할 수 없습니다. 앱 바인딩을 취소하거나 만료하면 해당 키의 유효한 라이프사이클 액세스 권한도 제거됩니다.

참고하세요: 예제 앱의 액세스 제어 레퍼런스 전체 경계에 대한 상세 내용.

API 키를 관리(편집)하는 방법은 무엇인가요?

Members 섹션에서 렌치 아이콘 목록에 있는 모든 RBAC 키에서 (관리)를 클릭하세요. 키 상세 페이지가 열리며 다음 작업을 수행할 수 있습니다:

• 키 이름.
• 다음 파일을 업데이트하세요: 조직 역할.
• 활성화 또는 비활성화 조직 생성 허용 키에 Admin 조직 역할이 부여된 경우.
• 추가, 삭제 또는 변경 앱별 역할.

클릭 “변경 사항 저장” 완료되면.

API 키를 재발급하려면 어떻게 하나요?

API 키의 secret 값을 재발급하려면, 새로고침 아이콘 (Regenerate)을 목록의 키에서 클릭하세요.

확인 대화 상자가 나타납니다. 확인을 누르면:

• 대상: 보안(해시화된) 키: 새로운 평문 키가 생성되어 모달에 한 번만 표시됩니다. 즉시 복사하세요.
• 대상: 평문 키: 키 값이 서버 측에서 재생성됩니다.

이전 키 값을 사용하는 모든 통합 기능이 즉시 중단됩니다.

API 키를 삭제하려면 어떻게 하나요?

Members 섹션에서 휴지통 아이콘 목록에 있는 키의 (Delete)를 클릭합니다. 대화 상자에서 삭제를 확인하세요.

키가 즉시 무효화됩니다. 해당 키를 사용하는 모든 요청은 실패합니다.

이전 방식의 키

만약 다음 섹션에서 이전 방식의 키 섹션(역할이 할당되지 않은 키)에 키가 보인다면, 이는 기존의 모드 기반 권한 시스템을read, upload, write, all)을 사용하고 있는 것입니다. 여전히 작동하지만 RBAC의 세분화된 권한 제어 기능은 사용할 수 없습니다.

이전 방식의 키는 목록에서 재발급하거나 삭제할 수 있지만, RBAC 역할을 추가하기 위해 수정할 수는 없습니다. 가급적 새로운 RBAC 키를 생성하고 이전 방식의 키는 삭제하는 것을 권장합니다.

이전 방식의 키를 직접 관리해야 하는 경우, 다음 경로에서 여전히 접근할 수 있습니다: console.capgo.app/dashboard/apikeys. 이 페이지는 지원이 중단될 예정이며 향후 업데이트에서 삭제됩니다.

API 키에서 계속하기

사용 중이라면 API 키 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 구현 세부 사항은 API 키에서 기기 구현 세부 사항은 기기에서, 그리고 번들 Bundles의 구현 세부 사항은