API 키

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

API 키 사용하기

엔드포인트에 명시된 인증 헤더를 사용하세요. API key 요청의 경우, authorization 형식이 허용됩니다:

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

일부 엔드포인트는 전용 키 헤더도 허용합니다. API 채널 는 다음을 허용합니다: authorization 또는 capgkey; preview-channel 자동화에는 해당 헤더 중 하나를 사용하세요.

RBAC 권한

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

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

API 키에 명시적인 역할 바인딩이 있으면, 해당 바인딩만 권한 확인에 사용됩니다. 키 소유자의 개인 권한은 키에 상속되지 않습니다.

Preview 채널 자동화

바인딩 app_preview 은(는) 임시 비공개 Preview 채널을 생성하고, bundle을 업로드 및 promote한 뒤, 채널과 bundle을 모두 삭제하는 CI용 Preview 앱에만 연결됩니다.

{
  "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. 해당 키로 채널을 생성하면 Capgo이 자동으로 channel_preview 새로 생성된 채널에 바인딩을 추가합니다. 이 하위 바인딩은 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 를 정리용으로 절대 사용하지 마세요. 이는 원자적이고 소유권이 확인된 프리뷰 정리 경로입니다. 호출한 키의 프리뷰 채널과 연결된 번들만 삭제합니다. app_preview 일반적인 권한은 부여하지 않습니다 bundle.delete.

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

참고

역할 바인딩이 없는 키는 레거시 모드 기반 시스템으로 폴백됩니다 (read, upload, write, all). 이 모드들은 더 이상 지원되지 않으므로 대신 RBAC 역할을 사용하세요.

조직 생성 권한

API 키로 조직을 생성할 때는 이제 명시적인 전역 권한을 사용합니다: org.create.

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

• API 키에 다음이 포함되어야 합니다 org.create 에서 global_permissions.
• 동일한 API 키에도 현재 조직 범위의 org_admin 또는 org_super_admin 바인딩이 있어야 합니다.
• 새 API 키는 기본적으로 org.create 권한을 받지 않습니다. 활성화하세요: 조직 생성 허용 대시보드에서 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.

보안(해시) 키

보안 키를 생성할 때 서버는 키 자료를 생성하고 평문 값을 한 번만 반환합니다. 해시만 저장됩니다. 즉, 다음과 같습니다:

• 평문 키는 다시 조회할 수 없으며 생성 후에는 확인할 수 없습니다.
• 키를 재생성하면 새 평문 키(한 번만 표시)가 생성되고 저장된 해시가 업데이트됩니다.
• 프로덕션에서는 해시 키 사용을 권장합니다.

일부 조직은 조직 정책을 통해 enforce_hashed_api_keys 해시된 키를 강제합니다.

만료

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

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

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

보안 모범 사례

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

주요 사용 사례

1. CI/CD 통합: 특정 앱으로 범위를 제한한 키를 app_uploader 또는 app_developer 역할로 생성하고 만료일을 설정하세요.
2. PR 프리뷰 채널: app_preview CI가 번들을 업로드하고 임시 채널을 생성한 뒤 자체 채널과 번들을 원자적으로 정리해야 할 때는 프리뷰 앱에만 적용하세요.
3. 배포 자동화: 자동화된 배포 스크립트에는 app_developer 역할의 키를 사용하세요.
4. 모니터링 도구: 외부 모니터링 통합을 위해 app_reader 역할로 키를 생성하세요.
5. 관리자 액세스: 자동화된 배포 스크립트에는 org_admin 역할은 관리 도구에만 신중하게 사용하세요.
6. 서드파티 통합: 최소 필수 역할로 특정 앱에만 제한된 키를 생성하세요.
7. 조직 프로비저닝: 다음을 사용하세요 org_admin 또는 org_super_admin RBAC 키와 함께 org.create 조직 생성이 필요한 신뢰할 수 있는 자동화 작업에만 사용하세요.

API 키에서 계속하기

사용 중이라면 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)의 구현 세부 사항은.