API 키

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

API 키는 Capgo API에 대한 요청을 인증하는 데 사용됩니다. 키는 조직별로 관리되며, 세밀한 액세스 제어를 위해 RBAC 역할을 할당할 수 있습니다. 또한 각 키에는 선택적으로 만료일을 설정할 수 있으며, 평문 값이 단 한 번만 표시되는 “secure”(해시) 키로 생성할 수도 있습니다.

API 키 사용하기

각 엔드포인트에 명시된 인증 헤더를 사용하세요. API 키 요청 시에는 다음 형식을 authorization 지원합니다:

curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

일부 엔드포인트는 전용 키 헤더도 지원합니다. 다음 헤더를 API 채널 에서 authorization 또는 capgkey를 사용하세요. preview-channel 자동화 시 이 헤더 중 하나를 사용하면 됩니다.

RBAC 권한

API 키는 사용자 계정과 동일한 역할 기반 액세스 제어(RBAC) 시스템을 사용합니다. 웹 앱이나 API을 통해 키를 생성하거나 관리할 때, 다음 두 단계에서 역할을 할당합니다:

조직(Organization) 역할 — 조직 전체에 적용되는 키의 기본 권한을 정의합니다 (예: org_admin 또는 org_member).
앱 역할 — 앱별 권한 (예: app_admin, app_developer, app_uploader, app_reader, 또는 app_preview).

만약 API 키에 명시적인 역할 바인딩이 설정되어 있다면, 권한 확인 시 해당 바인딩만 평가됩니다. 키 소유자의 개인 권한은 키로 상속되지 않습니다.

Preview 채널 자동화

Bind app_preview CI용 preview app에만 바인딩하여, 임시 비공개 preview channel을 생성하고 bundle을 upload 및 promote한 뒤 두 항목을 모두 삭제합니다.

{
  "name": "PR preview key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "app_preview",
      "scope_type": "app",
      "org_id": "<OWNING_ORG_UUID>",
      "app_id": "<APP_UUID>"
    }
  ]
}

org_id 앱 소유 조직의 UUID입니다. app_id 앱 레코드의 내부 UUID이며, CLI 명령에서 사용하는 공개 앱 식별자가 아닙니다 (예: com.example.app). 해당 키에 조직 전체 역할이 없더라도 바인딩은 조직에 귀속된 상태로 유지됩니다.

앱 레벨의 app_preview 역할은 다음 항목만 포함합니다: app.read, app.read_bundles, app.upload_bundle, 그리고 app.create_channel. 해당 키가 channel을 생성하면, Capgo이 자동으로 channel_preview 를 새로 생성된 channel에 binding합니다. 이 자식 binding은 channel.read, channel.promote_bundle, 그리고 channel.delete 해당 키가 생성된 채널에만 적용됩니다.

app_preview 유지됩니다 app.read, 따라서 엄격한 채널 읽기 격리는 아닙니다. 즉, 선택된 앱 내의 채널 메타데이터를 열람할 수 있습니다. 자동 자식 바인딩은 라이프사이클 변경 사항을 키가 생성한 채널로 제한합니다.

Capgo는 각 번들을 업로드한 App Preview 키를 기록합니다. 이 키는 자신이 생성한 각 프리뷰 채널에 대해 본인의 번들만 프로모션할 수 있습니다. 기존의 기본/메인 채널, 다른 프리뷰 키가 생성한 채널 또는 다른 키의 번들에 대해서는 채널 라이프사이클 접근 권한이 없습니다. 이 워크플로우에서는 public 를 생략하고 --default.

사용 channel delete <preview-channel> <public-app-id> --delete-bundle 를 정리용으로 사용하지 마세요. 이는 원자적(atomic)이며 소유권이 확인되는 프리뷰 정리 경로입니다. 호출한 키의 프리뷰 채널과 연결된 번들만 삭제합니다. app_preview 는 일반적인 bundle.delete.

대시보드 설정 및 전체 CLI 예시는 다음을 참조하세요. 프리뷰 워크플로우에는 App Preview 키를 사용하세요.

Organization 생성 권한

API 키로 Organization을 생성할 때는 이제 명시적인 글로벌 권한을 사용합니다: org.create.

이 권한은 일반적인 org/app 역할 바인딩과 별개입니다. 호출 시점에 아직 새로운 organization이 POST /organization/ 존재하지 않기 때문입니다. API 키로 Organization을 생성하려면:

API 키에 다음이 포함되어야 합니다 org.create 에서 global_permissions.
동일한 API 키에 대해 현재 조직 범위의 org_admin 또는 org_super_admin binding.
새로운 API 키에는 기본적으로 org.create by default. Enable 조직 생성 허용 대시보드에서 RBAC API 키를 생성하거나 수정할 때.
기존의 쓰기 권한을 가진 조직 관리자/슈퍼 관리자 API 키에는 org.create 가 소급 적용되어 기존 통합 환경에서 조직을 계속 생성할 수 있습니다.

API 키가 조직을 생성하면, Capgo이 해당 API 키를 org_super_admin 새로 생성된 조직에 자동으로 할당합니다. 이를 통해 통합 환경에서 별도의 수동 역할 바인딩 없이도 방금 생성한 조직을 직접 관리할 수 있습니다.

API를 통해 API 키를 생성할 때, 다음을 포함해야 합니다: global_permissions 조직 관리자(org admin) 바인딩과 함께:

{
  "name": "Provisioning key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "org_admin",
      "scope_type": "org",
      "org_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "global_permissions": ["org.create"]
}

org.create 조직 생성 시에만 적용됩니다. 조직을 삭제하려면 대상 조직에 대한 삭제 권한이 필요하며, 일반적으로 다음을 통해 수행됩니다: org_super_admin.

보안(해시화된) 키

Secure key를 생성하면 서버에서 키 값을 생성하여 평문(plain-text) 형태로 단 한 번만 반환합니다. 서버에는 해시값만 저장됩니다. 즉:

평문 키는 다시 조회할 수 없으며 생성 직후에만 확인 가능합니다.
키를 재생성하면 새로운 평문 키(단 한 번 표시됨)가 생성되고 저장된 해시값이 업데이트됩니다.
운영 환경에서는 Hashed key 사용을 권장합니다.

일부 조직은 다음을 통해 enforce_hashed_api_keys 조직 정책.

만료

키에는 선택적으로 만료일을 설정할 수 있습니다. 만료된 키는 권한 확인 단계에서 거부됩니다.

조직 정책으로 다음 사항을 강제할 수 있습니다:

만료 필수 (require_apikey_expiration) — 모든 새 키는 반드시 만료일이 있어야 합니다.
최대 TTL (max_apikey_expiration_days) — 만료일은 현재로부터 N일 이내여야 합니다.

보안 모범 사례

최소 권한 원칙: 통합 기능이 작동하는 범위 내에서 가장 제한적인 역할을 할당하세요
정기적인 키 교체: regenerate 기능을 사용하여 API 키를 주기적으로 교체하세요
보안 스토리지: API 키를 안전하게 보관하고 버전 관리 시스템에 커밋하지 마세요
해시 키 사용: 프로덕션 환경 통합을 위해 보안(해시) 키를 생성하세요
만료일 설정: 임시 액세스 또는 CI/CD용 키에는 항상 만료일을 설정하세요
범위 제한: 키의 권한을 최소한의 역할로 제한하고 특정 앱에만 적용하세요

주요 사용 사례

CI/CD 통합: 특정 앱에 권한을 제한한 키를 생성하고, app_uploader 또는 app_developer 만료 날짜를 설정할 수 있습니다.
PR Preview 채널: app_preview CI에서 번들을 upload하고 임시 채널을 생성해야 할 때, 프리뷰 앱에만 적용하여 채널과 번들을 원자적으로 자동 정리합니다.
배포 자동화: 자동 배포 스크립트에는 app_developer role 권한이 있는 키를 사용하세요.
모니터링 도구: 외부 모니터링 연동을 위해 app_reader 역할을 가진 키를 생성하세요.
관리자 권한: 관리 도구용 키는 org_admin 역할을 부여하여 신중하게 사용하세요.
서드파티 연동: 최소 권한만 가진 역할로 특정 앱에 제한된 키를 생성하세요.
조직 프로비저닝: 다음을 사용하는 org_admin 또는 org_super_admin RBAC 키 org.create 조직(organization) 생성이 필요한 신뢰할 수 있는 자동화 작업에만 사용하세요.

API Keys에서 계속하기

사용 중이라면 API 키 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은, 2단계 인증 2단계 인증(Two-factor authentication)의 구현 세부 사항은, SSO (기업용) SSO (Enterprise)의 구현 세부 사항은.