API 키

설치 단계와 이 플러그인의 전체 마크다운 가이드가 포함된 설정 지시어를 복사할 수 있습니다.

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

API 키를 사용하여

API 키를 x-api-key 요청의 헤더에 __CAPGO_KEEP_0__ 키를 전달하세요:

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

__CAPGO_KEEP_0__ 키는 헤더도 지원하지만 JWT 토큰에 주로 사용됩니다. UUID 형식의 __CAPGO_KEEP_0__ 키를 사용하면 작동하지만, 모든 키 유형(secure/hashed 키 포함)에서 권장되는 헤더입니다. authorization header is also accepted but is primarily intended for JWT tokens. When the value is a UUID-formatted API key it works, but x-api-key 권한 관리

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

API 키 사용 방법

Organization role — 전체 조직에서 키의 기본 권한을 정의합니다 (예 org_admin, org_member).
App roles — 앱별 권한 (예 app_admin, app_developer, app_uploader, app_reader).

If an API key has explicit role bindings, only those bindings are evaluated for permission checks. The key owner’s personal permissions are not inherited by the key.

A diagram explaining how RBAC API key permissions work

__CAPGO_KEEP_0__

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

이 권한은 일반적인 org/app 역할 바인딩과 분리된 것입니다. 왜냐하면 __CAPGO_KEEP_0__ 키가 호출될 때 조직이 아직 존재하지 않기 때문입니다. POST /organization/ API 키를 사용하여 조직을 생성하려면:

API 키는 org.create __CAPGO_KEEP_0__ 키는 global_permissions.
API 키는 현재 조직 범위의 org_admin __CAPGO_KEEP_0__ 키는 org_super_admin __CAPGO_KEEP_0__ 키는 기본적으로
API 키를 사용하여 조직을 생성하려면 API 키를 활성화해야 합니다. org.create __CAPGO_KEEP_0__ 키를 활성화해야 합니다. 조직 만들기 허용 대시보드에서 RBAC API 키를 만들거나 편집할 때 API
기존에 쓰기 가능한 조직 관리자/슈퍼 관리자 API 키가 org.create 기존 통합이 조직을 계속 만들 수 있도록 existing integrations가 __CAPGO_KEEP_0__

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

API을 통해 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 조직 만들기만 해당됩니다. 조직을 삭제하는 경우에는 일반적으로 대상 조직에 대한 삭제 권한이 필요합니다. org_super_admin.

보안(해시) 키

보안 키를 생성할 때 서버는 키 자료를 생성하고 평문 값을 한 번만 반환합니다. 이 경우에만 해시만 저장됩니다. 이는 다음과 같은 의미를 가지고 있습니다:

__CAPGO_KEEP_0__ 평문 키 생성 후 평문 키를 다시 가져올 수 없습니다.
재생성은 새로운 평문 키(한 번만 표시)를 생성하고 저장된 해시를 업데이트합니다.
생산 환경에서 해시된 키 사용이 권장됩니다.

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

만료 섹션

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

Some organizations enforce hashed keys via the __CAPGO_KEEP_0__ policy.

필수 만료 (require_apikey_expiration) — 모든 새로운 키는 만료일을 가져야 합니다.
최대 TTL (max_apikey_expiration_days) — 만료일은 현재 날짜에서 N일 이내여야 합니다.

보안 최적화

최소 권한 원칙: 사용 가능한 가장 제한적인 역할을 Assign 하세요.
정기적인 회전: API 키를 regenerate 기능을 사용하여 정기적으로 회전하세요.
안전한 저장: API 키를 안전하게 저장하고 버전 관리에 포함하지 마세요.
__CAPGO_KEEP_0__:
: :
: :

:

: : app_uploader : app_developer :
배포 자동화: __CAPGO_KEEP_0__ 키와 함께 사용하세요. app_developer 자동 배포 스크립트의 역할로 키를 사용하세요.
모니터링 도구: __CAPGO_KEEP_0__ 키와 함께 외부 모니터링 통합을 생성하세요. app_reader 관리자 접근
: __CAPGO_KEEP_0__ 키와 함께 관리자 도구에 사용하세요.세 번째 통합 org_admin : __CAPGO_KEEP_0__ 키와 함께 최소한의 역할로 특정 앱에 제한된 키를 생성하세요.
조직 제공__CAPGO_KEEP_0__
__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-passkey @capgo/capacitor-passkey, @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric, 두 단계 인증 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-biometric, 기업 SSO @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-biometric.