API 키

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 지시를 복사합니다.

API 키는 Capgo API에 대한 인증 요청을 인증하기 위해 사용됩니다. 키는 조직별로 지정되며 RBAC 역할 assign을 통해 세부적인 접근 제어를 할 수 있습니다. 각 키에는 선택적 유효 기간이 있을 수 있으며, 평문 값이 한 번만 표시되는 “secure” (해시) 키로 생성할 수 있습니다.

API 키를 사용하는 경우

API 키를 사용하는 경우, 인증 헤더는 엔드포인트에 의해 문서화된 것을 사용합니다. authorization 수락됩니다:

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

일부 엔드포인트는 전용 키 헤더도 수락합니다. API 채널 __CAPGO_KEEP_0__ 채널 authorization 또는 ; 사용자 채널 자동화의 예시를 위해 하나의 헤더를 사용하세요. capgkeyRBAC 권한

“RBAC 권한”이라는 제목을 가진 섹션

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app or API, you assign roles at two levels:

— 조직 전체에서 키의 기본 권한을 정의합니다 (예를 들어, or org_admin 앱 역할 org_member).
— 앱별 권한 (예를 들어, , 또는 app_admin, app_developer, app_uploader, app_reader만약 __CAPGO_KEEP_0__ 키에 명시적 역할 바인딩이 있다면, app_preview).

If an API key has explicit role bindings, 단지 바인딩 권한 검사에 사용되는 바인딩은 __CAPGO_KEEP_0__만이 평가됩니다. 키 소유자의 개인 권한은 키에 의해 상속되지 않습니다.

미리보기 채널 자동화

바인딩 app_preview CI가 임시, 비공개 미리보기 채널을 생성하고, 패키지를 업로드하고, 승격한 후에 삭제하는 데 사용됩니다.

{
  "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 __CAPGO_KEEP_0__ 명령어에 사용되는 공개 앱 식별자와는 다릅니다. app.read, app.read_bundles, app.upload_bundle그리고 app.create_channel키가 채널을 생성할 때, Capgo 자동으로 새로 생성된 채널에 대한 channel_preview 바인딩을 추가합니다. 그 자식 바인딩은 키가 생성한 채널에 대해서만 channel.read, channel.promote_bundle그리고 channel.delete 만 허용합니다. __CAPGO_KEEP_0__는 앱 프리뷰 키가 업로드한 각 번들을 기록합니다. 키는 자신이 생성한 프리뷰 채널에 대해서만 번들을 승격할 수 있습니다. 키는 기존 기본/메인 채널, 다른 프리뷰 키가 생성한 채널, 또는 다른 키의 번들과 관련된 채널 라이프 사이클 접근 권한이 없습니다. 이 워크플로우에서

app_preview omitted app.read사용하지 마십시오. 사용하지 마십시오. __CAPGO_KEEP_0__

Capgo public __CAPGO_KEEP_0__ --default.

__CAPGO_KEEP_0__ channel delete <preview-channel> <public-app-id> --delete-bundle 청소하기. 이 경로는 소유권 확인을 통해 원자적 청소 경로입니다. 호출 키의 미리보기 채널과 연결된 번들을 제거합니다. app_preview 일반적인 권한을 부여하지 않습니다. bundle.delete.

대시보드 설정 및 완전한 CLI 예제를 보려면 미리보기 워크플로우에 App Preview 키를 사용하세요..

조직 생성 권한

조직을 생성하는 데 API 키를 사용할 때 이제 명시적 글로벌 권한을 사용합니다. org.create.

이 권한은 일반적인 org/app 역할 바인딩과 분리되어야 하는데, 새로운 organization이 아직 존재하지 않기 때문이다. __CAPGO_KEEP_0__를 호출할 때 POST /organization/ organization을 생성하기 위해 API key를 포함하는 organization을 만들려면:

API key는 org.create in global_permissions.
API key는 또한 현재 organization-scoped org_admin or org_super_admin binding을 포함해야 한다.
새로운 API key는 기본적으로 org.create by default 받지 못한다. __CAPGO_KEEP_0__ key를 활성화하여 when creating or editing an RBAC API key in the dashboard.
when creating or editing an RBAC API key in the dashboard에 있는 경우에만 생성할 수 있다. existing write-capable org admin/super admin API key는 backfilled되었다. org.create 기존 통합을 통해 계속해서 조직을 만들 수 있습니다.

API 키가 조직을 만들면 Capgo은 자동으로 같은 API 키를 할당합니다. org_super_admin 새로 생성된 조직에 적용됩니다. 이로 인해 통합은 생성한 조직을 관리할 수 있습니다. 별도의 수동 역할 바인딩이 필요하지 않습니다.

API 키를 API을 통해 생성할 경우, org admin 바인딩과 함께 포함되어야 합니다. 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 조직을 삭제하는 경우에는 대상 조직에 대한 삭제 권한이 필요합니다. 일반적으로 __CAPGO_KEEP_1__을 통해 삭제 권한이 필요합니다. org_super_admin.

Secure (Hashed) Keys

조직을 생성할 때 서버는 키 자료를 생성하고 평문 키 값을 반환합니다. 평문 키는 저장되지 않습니다. 해시만 저장됩니다. 이로 인해:

평문 키 조직을 삭제하는 경우에는 대상 조직에 대한 삭제 권한이 필요합니다. 일반적으로 __CAPGO_KEEP_1__을 통해 삭제 권한이 필요합니다. __CAPGO_KEEP_0__
생성 후 재생산은 새로운 평문 키 (한 번만 표시)와 저장된 해시를 업데이트합니다.
해시된 키는 프로덕션 용도로 권장됩니다.

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

제한 시간

키는 선택적 유효 기간을 가질 수 있습니다. 유효 기간이 만료된 키는 허용 체크層에서 거부됩니다.

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

유효 기간이 있는 키만 생성해야 합니다. (require_apikey_expiration최대 TTL
최대 유효 시간 (max_apikey_expiration_days — __CAPGO_KEEP_0__ 일 수는 현재보다 __CAPGO_KEEP_0__ 일 이하여야 합니다.

보안 최적화

권한 최소화 원칙: 가능한 한 제한적인 역할을 할당하여 통합이 작동할 수 있도록 하세요.
정기적인 키 회전: API 키를 regenerate 기능을 사용하여 정기적으로 회전하세요.
안전한 키 저장: API 키를 안전하게 저장하고 버전 관리에 포함하지 마세요.
해시된 키 사용: 프로덕션 통합을 위한 안전한 (해시된) 키를 생성하세요.
만료일 설정: Always set an expiration date on keys used for temporary or CI/CD access
Scope 제한: Key를 특정 앱에만 제한하고 최소 권한으로 설정합니다.

일반적인 사용 사례

CI/CD 통합: 특정 앱에 Key를 제한하고 최소 권한을 설정한 후 만료일을 설정합니다. app_uploader PR 미리보기 채널 app_developer : CI가 패키지를 업로드하고 임시 채널을 생성하며, 채널과 패키지를 자동으로 삭제할 때 미리보기 앱 또는 앱만 사용합니다.
orrole app_preview and
배포 자동화: __CAPGO_KEEP_0__ 키와 함께 사용하세요. app_developer 자동화 배포 스크립트를 위한 역할을 부여합니다.
모니터링 도구: __CAPGO_KEEP_0__ 키와 함께 사용하세요. app_reader 외부 모니터링 통합을 위한 역할을 부여합니다.
관리자 접근: __CAPGO_KEEP_0__ 키와 함께 사용하세요. org_admin 관리자 도구를 위한 역할을 신중하게 부여합니다.
세 번째 통합: __CAPGO_KEEP_0__ 키와 함께 사용하세요.
특정 앱에 제한된 역할을 부여하여 최소 권한으로 통합합니다. : 사용자 org_admin 또는 org_super_admin RBAC 키와 org.create 만 신뢰할 수 있는 자동화만이 조직을 만들기 위해 사용할 수 있습니다.

API 키에서 계속

만약 __CAPGO_KEEP_0__ 키를 사용 중이라면 API 키 인증 및 계정 흐름을 계획하기 위해 사용 중이라면 __CAPGO_KEEP_0__ 키를 연결하세요. @capgo/capacitor-social-login capgo/capacitor-social-login의 implementation detail에 대한 자세한 내용은 @capgo/capacitor-social-login에서 확인할 수 있습니다. @capgo/capacitor-passkey for the implementation detail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, 두 단계 인증 for the implementation detail in 두 단계 인증, and SSO (기업) for the implementation detail in SSO (기업).