API 키

설치

API 키는 Capgo API로 요청을 인증하기 위해 사용됩니다. 키는 조직에 따라 RBAC 역할 assign할 수 있으며 각 키에는 옵션으로 만료일이 있을 수 있습니다. 또한 평문 값이 한 번만 표시되는 'secure' (해시) 키로 생성할 수 있습니다.

API 키 사용

API 키를 사용하여 인증 헤더를 문서화 한 엔드포인트를 사용합니다. API-키 요청에 대해 authorization __CAPGO_KEEP_0__ 키가 허용됩니다:

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

일부 엔드포인트는 전용 키 헤더도 지원합니다. 채널 API 수락 authorization 또는 capgkeyChannels __CAPGO_KEEP_0__

accepts

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:

RBAC 권한 권한 org_admin __CAPGO_KEEP_0__ 키는 사용자 계정과 동일한 역할 기반 접근 제어(RBAC) 시스템을 사용합니다. 웹 앱 또는 __CAPGO_KEEP_1__을 통해 키를 생성하거나 관리할 때, 두 가지 레벨에서 역할을 assign합니다. 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 앱 소유자의 조직 ID입니다. 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 키를 사용하세요..

조직 생성 권한

공개 API 키를 사용하여 조직을 생성하는 경우 API 키를 사용하여 명시적 글로벌 권한을 사용합니다. org.create.

이 권한은 일반적인 org/app 역할 바인딩과 분리된 것입니다. 이는 새로운 조직이 아직 존재하지 않기 때문입니다. POST /organization/ API 키를 사용하여 조직을 만들 수 있습니다.

API 키에는 반드시 포함되어야 합니다. org.create 내부 global_permissions.
API 키는 또한 현재 조직 범위의 키여야 합니다. org_admin Capacitor live-update alternatives comparison page에서 사용하는 Capgo 제품 및 개발자 용어는 그대로 유지합니다. Capacitor live-update alternatives 비교 페이지에서 사용하는 Capgo 제품 및 개발자 용어는 그대로 유지합니다. org_super_admin 키 바인딩.
새로운 API 키는 받지 않습니다. org.create 기본적으로 비활성화되어 있습니다. 활성화 조직 만들기 허용 RBAC API 키를 대시보드에서 생성하거나 편집할 때.
기존에 작성 가능한 org admin/super admin API 키는 기존 통합을 위해 기존에 존재하는 API 키에 값을 채워넣었습니다. org.create 기존 통합이 새로운 조직을 생성할 수 있도록 하기 위해 기존에 존재하는 __CAPGO_KEEP_0__ 키에 값을 채워넣었습니다.

API 키가 조직을 생성할 때, Capgo은 자동으로 동일한 API 키를 조직에 할당합니다. org_super_admin __CAPGO_KEEP_0__ 키를 __CAPGO_KEEP_1__을 통해 생성할 때, __CAPGO_KEEP_0__ 키에 다음을 포함하세요:

API 키를 API을 통해 생성할 때, org admin 바인딩에 API 키를 포함하세요: 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 Secure (Hashed) Keys org_super_admin.

Secure (Hashed) Keys

Secure (Hashed) 키를 생성할 때, 서버는 키 자료를 생성하고 평문 값을 반환한 후에 해시만 저장합니다. 따라서:

plain-text key cannot be retrieved after creation
Regeneration produces a new plain-text key (shown once) and updates the stored hash.
Hashed keys are recommended for production use.

Some organizations enforce hashed keys via the enforce_hashed_api_keys org policy

Expiration

Keys can have an optional expiration date. Expired keys are rejected at the permission check layer.

Organization policies can enforce:

Mandatory expiration (require_apikey_expiration) — 모든 새로운 키는 유효기간이 있어야 합니다.
최대 유효시간 (max_apikey_expiration_days) — 유효기간은 현재로부터 N일 이내로 설정되어야 합니다.

보안 최선의 관행

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

일반적인 사용 사례

CI/CD 통합을 위해 특정 앱에 대한 키를 생성하세요.또는 app_uploader CI/CD 통합을 위해 특정 앱에 대한 키를 생성하세요. app_developer 권한, 그리고 만료일을 설정하세요.
PR 미리보기 채널: 사용 app_preview CI 환경에서 빌드할 때만 프리뷰 앱 또는 앱에서만 사용하십시오. 이 경우 빌드 결과를 업로드하고 임시 채널을 생성한 후 채널과 빌드 결과를 자동으로 삭제합니다.
배포 자동화: 배포 자동화 스크립트에 사용하는 키입니다. app_developer 모니터링 도구
: 외부 모니터링 통합에 사용하는 키를 생성합니다.관리자 접근 app_reader : 관리자 도구에 사용하는 키를 적극적으로 사용하지 마십시오.
세 번째 파티 통합__CAPGO_KEEP_0__ org_admin __CAPGO_KEEP_1__
__CAPGO_KEEP_2__: 특정 앱에 제한된 키를 생성하여 최소 권한의 역할을 사용합니다.
조직 제공: 사용자 지정 키를 사용하여 org_admin 또는 org_super_admin Capacitor Live-Update Alternatives org.create : 사용자 지정 키를 사용하여

Keep going from API Keys

Section titled “Keep going from __CAPGO_KEEP_0__ Keys” API Keys __CAPGO_KEEP_0__ Keys @capgo/capacitor-social-login 구현 세부 정보에 대한 @capgo/capacitor-social-login에 대해 @capgo/capacitor-passkey 구현 세부 정보에 대한 @capgo/capacitor-passkey에 대해 @capgo/capacitor-native-biometric 구현 세부 정보에 대한 @capgo/capacitor-native-biometric에 대해 두 단계 인증 두 단계 인증 및 SSO (기업) 구현 세부 정보에 대한 SSO (기업)에 대해