API 키

설치

API 키는 Capgo API로 요청을 인증하기 위해 사용됩니다. 키는 조직에 따라서 할당된 RBAC 역할에 따라 세부적인 접근 제어를 위해 할당할 수 있습니다. 각 키에는 선택적으로 만료 날짜가 있을 수 있으며, 평문 값이 단 한번만 표시되는 “secure” (해시된) 키로 생성할 수 있습니다.

API 키 사용

API 키를 사용하는 경우 authorization __CAPGO_KEEP_0__ 키를 사용하는 경우

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

또한 일부 엔드포인트는 전용 키 헤더를 지원합니다. 채널 API 받아들이거나 authorization 또는 capgkey자동화된 미리보기 채널을 위해 하나의 헤더를 사용하십시오.

RBAC 권한

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

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

API 키가 명시적인 역할 할당이 있는 경우 만 해당 할당 만 평가됩니다. 키 소유자의 개인 권한은 키에 의해 상속되지 않습니다.

미리보기 채널 자동화

만들기 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). The binding remains organization-bound even when the key has no organization-wide role.

앱 수준 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_KEEP_0__은 각 번들을 업로드한 App Preview 키를 기록합니다. 키는 각 프리뷰 채널에서만 자신의 번들을 승격할 수 있습니다. 기존 기본/메인 채널, 다른 프리뷰 키가 생성한 채널, 또는 다른 키의 번들과 관련된 채널 생명주기 접근 권한은 없습니다. 이 워크플로우에서 omit을 생략하세요.

Capgo records the App Preview key that uploaded each bundle. The key can promote only its own bundle to each preview channel it creates. It has no channel lifecycle access to an existing default/main channel, a channel created by another preview key, or another key’s bundle. For this workflow, omit public 그리고 절대 사용하지 마세요. --default.

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

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

조직 생성 권한

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

This permission is separate from normal org/app role bindings because a new organization does not exist yet when POST /organization/ API 키를 사용하여 조직을 생성하려면:

The API key must include org.create in global_permissions.
The same API key must also have a current organization-scoped org_admin or org_super_admin __CAPGO_KEEP_0__ 키는 기본적으로
API 키를 사용하여 조직을 생성하는 것을 허용합니다. org.create binding. __CAPGO_KEEP_0__ 키가 새로 생성되면 기본적으로 RBAC API 키를 생성하거나 편집할 때.
기존에 쓰기 가능한 org admin/super admin API 키는 기존 통합을 위해 기존에 존재하던 API 키에 백필드되었습니다. org.create 이러한 __CAPGO_KEEP_0__ 키가 조직을 생성하면 __CAPGO_KEEP_1__은 자동으로 동일한 __CAPGO_KEEP_2__ 키를 조직에 할당합니다.

When an API key creates an organization, Capgo automatically assigns that same API key as org_super_admin 조직 admin 바인딩과 함께 __CAPGO_KEEP_0__ 키를 포함합니다:

If you create an API key through the API, include global_permissions 조직을 생성하는 경우에만 적용됩니다. 조직을 삭제하는 경우에는 대상 조직에 대한 삭제 권한이 필요하며, 일반적으로 __CAPGO_KEEP_0__을 통해 삭제합니다.

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

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

Secure (Hashed) Keys

plain-text key 얻을 수 없습니다 생성 후
새로운 plain-text key (한 번만 표시)과 저장된 해시를 업데이트하는 키 재생성
제품 환경에서 사용하는 것이 권장되는 해시된 키

해시된 키는 org 정책을 통해 강제될 수 있습니다 enforce_hashed_api_keys 만료

만료 날짜가 있는 키

만료 날짜가 있는 키는 허용 체크層에서 거부됩니다

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

만료 날짜가 필수적입니다 (require_apikey_expiration) — 모든 새로운 키는 만료일이 있어야 합니다.
최대 유효 시간 (max_apikey_expiration_days) — 만료일은 현재 날짜에서 N일 이내로 설정할 수 없습니다.

보안 최선의 관행

권한 제한의 원칙: 기능을 수행할 수 있는 가장 제한적인 역할을 할당하세요.
정기적인 회전: API 키를 regenerate 기능을 사용하여 정기적으로 회전하세요.
안전한 저장: API 키를 안전하게 저장하고 버전 관리에 포함하지 마세요.
해시된 키 사용: 프로덕션 통합을 위한 보안 (해시) 키를 생성하세요.
만료일 설정: 임시 또는 CI/CD 액세스에 사용되는 키에 항상 만료일을 설정하세요.
권한 제한: 최소 권한이 필요한 앱에만 키를 제한하세요.

일반적인 사용 사례

: 특정 앱에 대한 키를 생성하세요.또는 app_uploader 권한, 그리고 만료일을 설정하세요. app_developer PR 미리보기 채널
권한, 그리고 만료일을 설정하세요.: 사용 app_preview CI가 번들을 업로드하고 임시 채널을 만들고 채널과 번들을 원자적으로 정리해야 하는 경우에만 프리뷰 앱 또는 앱에 사용
배포 자동화: 자동 배포 스크립트에 사용할 키 app_developer 모니터링 도구
: 외부 모니터링 통합에 사용할 키를 생성관리자 접근 app_reader : 관리자 도구에 사용할 키를 적극적으로 사용하지 마세요
세 번째 파티 통합__CAPGO_KEEP_0__ org_admin __CAPGO_KEEP_1__
__CAPGO_KEEP_2__: __CAPGO_KEEP_0__ 키를 생성하여 최소 권한의 역할에 따라 특정 앱에 제한합니다.
조직 제공: __CAPGO_KEEP_0__ org_admin 또는 org_super_admin Capacitor live-update 대안을 비교할 때 사용하는 HTML 텍스트 조각입니다. 페이지/영역: Capacitor live-update 대안 비교 페이지. 역할: 장기 마케팅 또는 법률 문단. 표시되는 곳: page alternatives.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다. 메시지 키 `alternatives_cta_questions` (대안 CTA 질문). | HTML 텍스트 조각은 더 긴 Capgo UI 문자열 (부모 키 `appflow_cta_questions`)에서 가져옵니다. 페이지/영역: Appflow 비교/이동 마케팅 복사본. 역할: 장기 마케팅 또는 법률 문단. 표시되는 곳: page ionic-appflow.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다. 메시지 키 `appflow_cta_questions` (Appflow CTA 질문). | HTML 텍스트 조각은 더 긴 Capgo UI 문자열 (부모 키 `capwesome_cta_questions`)에서 가져옵니다. 페이지/영역: Capawesome 비교 페이지. 역할: 장기 마케팅 또는 법률 문단. 표시되는 곳: page capwesome.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다. 메시지 키 `capwesome_cta_questions` (Capwesome CTA 질문). | HTML 텍스트 조각은 더 긴 Capgo UI 문자열 (부모 키 `consulting_faq_subtitle`)에서 가져옵니다. 페이지/영역: 컨설팅 서비스 페이지. 역할: 섹션 서브 타이틀 또는 태그 라인. 표시되는 곳: page consulting.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다. 메시지 키 `consulting_faq_subtitle` (컨설팅 FAQ 서브 타이틀). | 페이지/영역: Appflow 비교/이동 마케팅 복사본. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 표시되는 곳: page ionic-appflow.astro, page ionic-enterprise-plugins.astro, page solutions/ionic-enterprise-plugins.astro. 메시지 키 `appflow_plugins_or` (Appflow 플러그인 또는). org.create RBAC 키는

Keep going from API Keys

__CAPGO_KEEP_0__ 키를 계속 사용하세요. API 키를 계속 사용하세요. __CAPGO_KEEP_0__ 키를 계속 사용하세요. @capgo/capacitor-social-login 구현 세부 정보에 대한 @capgo/capacitor-social-login 에 대해 @capgo/capacitor-passkey 구현 세부 정보에 대한 @capgo/capacitor-passkey 에 대해 @capgo/capacitor-native-biometric 구현 세부 정보에 대한 @capgo/capacitor-native-biometric 에 대해 두 단계 인증 구현 세부 정보에 대한 두 단계 인증 및 SSO (기업) 구현 세부 정보에 대한 SSO (기업).