메뉴로 바로가기
Capgo - Capacitor 앱의 실시간 업데이트 Capgo

API 키

API 키는 Capgo API에 대한 인증 요청을 인증하기 위해 사용됩니다. 키는 조직별로 할당되고 RBAC 역할을 할당하여 세부적인 접근 제어를 할 수 있습니다. 각 키에는 선택적 만료 날짜도 있을 수 있고, 평문 값이 단 한 번만 표시되는 “보안” 키로 생성할 수도 있습니다.

API 키를 사용합니다.

API 키를 사용하는 방법

API 키 요청에 대해 문서화된 인증 헤더를 사용하십시오. authorization 허용됩니다.

터미널 창
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

일부 엔드포인트는 전용 키 헤더도 받습니다. API 채널 받습니다. authorization 또는 capgkey; 예시 채널 자동화에 사용하세요.

권한 관리

__CAPGO_KEEP_0__ 권한 관리

API 키는 사용자 계정과 동일한 역할 기반 접근 제어 (RBAC) 시스템을 사용합니다. 웹 앱 또는 API을 통해 키를 생성하거나 관리할 때, 두 가지 레벨에서 역할을 Assign합니다.

  • Organization 역할 — 전체 조직에 걸쳐 키의 기본 권한을 정의합니다 (예를 들어, org_admin or org_member).
  • App 역할 — 앱별 권한 (예를 들어, app_admin, app_developer, app_uploader, app_reader, app_preview).

If an API key has explicit role bindings, 만약 __CAPGO_KEEP_0__ 키가 명시적 역할 바인딩을 가지고 있다면, 그것만

권한 검사에 평가됩니다. 키 소유자의 개인 권한은 키에 상속되지 않습니다.

기본 채널 자동화

CI 환경에서 임시, 비공개 프리뷰 채널을 생성하고, 업로드하고, 승격한 후에 삭제하는 데 사용되는 프리뷰 앱에만 바인딩하세요. app_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입니다. __CAPGO_KEEP_0__ 명령 (예를 들어, )에 의해 사용되는 공개 앱 식별자와 다릅니다. app_id is the app record’s internal UUID, not the public app identifier used by CLI commands (for example, com.example.app앱 수준

역할은 app_preview , app.read, app.read_bundles, app.upload_bundle, app.create_channel. When that key creates a channel, Capgo automatically adds a channel_preview , channel.read, channel.promote_bundle, channel.delete __CAPGO_KEEP_0__만 해당 채널에 생성된 키에 대해만 사용됩니다.

app_preview __CAPGO_KEEP_0__ app.read, 따라서 이건 엄격한 채널 읽기 격리가 아닙니다. 선택된 앱에서 채널 메타데이터를 열거할 수 있습니다. 자동 자식 바인딩 제한 __CAPGO_KEEP_0__ __CAPGO_KEEP_0__

Capgo public __CAPGO_KEEP_0__ --default.

__CAPGO_KEEP_0__ channel delete <preview-channel> <public-app-id> --delete-bundle __CAPGO_KEEP_0__ app_preview __CAPGO_KEEP_0__ bundle.delete.

CLI __CAPGO_KEEP_0__.

RBAC API 키 권한의 다이어그램

조직 생성 권한

조직 생성 권한

조직을 생성하는 API 키는 명시적 글로벌 권한을 사용합니다: org.create.

이 권한은 일반적인 org/app 역할 바인딩과 분리됩니다. 조직이 아직 존재하지 않기 때문입니다. POST /organization/ 조직을 생성하는 API 키를 사용하려면:

  • API 키는 다음 항목을 포함해야 합니다: org.create in global_permissions.
  • The same API key must also have a current organization-scoped org_admin 또는 org_super_admin binding.
  • 새로운 API 키는 기본적으로 org.create by default. Enable 조직 만들기 허용 when creating or editing an RBAC API key in the dashboard.
  • 기존에 쓰기 가능한 org admin/super admin API 키는 org.create so existing integrations can continue creating organizations.

When an API key creates an organization, Capgo automatically assigns that same API key as org_super_admin __CAPGO_KEEP_2__ 키를

on the newly created organization. This lets the integration manage the organization it just created without needing a separate manual role binding. If you create an API key through the API, include global_permissions 관리자와의 연결: 

{
  "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 (Hashed) Keys

Secure (Hashed) Keys

생성할 때 보안 키를 만들 때 서버는 키 자료를 생성하고 평문 값을 한 번만 반환합니다. 저장된 것은 해시만입니다. 이것은:

  • 평문 키 생성 후 생성 후 다시 생성하면 새로운 평문 키(한 번만 표시)와 저장된 해시를 업데이트합니다.
  • 해시 키는 프로덕션 환경에서 권장됩니다.
  • 일부 조직은

해시 키를 강제로 사용합니다. enforce_hashed_api_keys 회사 정책.

만료

제목: 만료

키는 만료일을 선택적으로 지정할 수 있습니다. 만료된 키는 허가 검사 계층에서 거부됩니다.

회사 정책은 다음과 같이 강제할 수 있습니다:

  • 필수 만료 (require_apikey_expiration) — 모든 새로운 키는 만료일을 지정해야 합니다.
  • 최대 TTL (max_apikey_expiration_days) — 만료일은 현재로부터 N일 이내여야 합니다.

보안 최선의 관행

제목: 보안 최선의 관행
  1. 권한 제한 원칙: __CAPGO_KEEP_0__를 사용하는 통합이 작동할 수 있는 가장 제한적인 역할을 할당하세요.
  2. 정규 회전: API 키를 정기적으로 갱신하기 위해 재생성 기능을 사용하세요.
  3. 안전한 저장소: API 키를 안전하게 저장하고 버전 관리에 포함하지 마세요.
  4. 해시된 키 사용: 프로덕션 통합에 사용하는 해시된 키를 생성하세요.
  5. 만료일 설정: 임시 또는 CI/CD 액세스에 사용하는 키에 항상 만료일을 설정하세요.
  6. 범위 제한: 최소한의 역할에 필요한 앱에만 키를 제한하세요.

일반적인 사용 사례

__CAPGO_KEEP_0__
  1. CI/CD 통합: 특정 앱에 대한 키를 스코프로 생성하고 app_uploader 또는 app_developer 역할을 설정하고 만료일을 설정합니다.
  2. PR 미리보기 채널: CI가 번들을 업로드할 때, 미리보기 앱 또는 앱에만 사용하고, 임시 채널을 생성하고, 채널과 번들을 원자적으로 삭제합니다. app_preview 배포 자동화
  3. : 자동화 배포 스크립트에 사용하는 키의 역할을 설정합니다.모니터링 도구 app_developer CI/CD 통합
  4. : 특정 앱에 대한 키를 스코프로 생성하고 역할을 설정하고 만료일을 설정합니다.: __CAPGO_KEEP_0__ 키를 외부 모니터링 통합에 사용하세요. app_reader 관리자 접근 권한
  5. : __CAPGO_KEEP_0__ 키를 관리자 도구에 사용하세요.세 번째-party 통합 org_admin : __CAPGO_KEEP_0__ 키를 특정 앱에 제한하여 최소 권한의 역할로 사용하세요.
  6. 조직 제공: __CAPGO_KEEP_0__ 키 또는 RBAC 키를 신뢰할 수 있는 자동화에만 사용하세요.
  7. only for trusted automation that needs to create organizations.__CAPGO_KEEP_0__ org_admin __CAPGO_KEEP_0__ org_super_admin __CAPGO_KEEP_0__ org.create __CAPGO_KEEP_0__

API 키를 계속 사용하세요.

API 키를 계속 사용하세요.

__CAPGO_KEEP_0__ 키를 사용 중이라면 API 키 __CAPGO_KEEP_0__ 키를 사용하여 인증 및 계정 흐름을 계획하고, @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 정보를 참조하세요 @capgo/capacitor-social-login, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 정보를 참조하세요 @capgo/capacitor-passkey, @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 정보를 참조하세요 @capgo/capacitor-native-biometric, 두 단계 인증 __CAPGO_KEEP_0__의 구현 세부 사항에 대해 SSO (기업) __CAPGO_KEEP_0__의 구현 세부 사항에 대해