API 키

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

API 키를 사용하는 경우

API 키를 요청 헤더에 전달합니다. x-api-key __CAPGO_KEEP_0__ 키를 요청 헤더에 전달합니다.

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

__CAPGO_KEEP_0__ 키를 요청 헤더에 전달합니다. authorization API 키를 요청 헤더에 전달합니다. x-api-key __CAPGO_KEEP_0__ 키를 요청 헤더에 전달합니다.

__CAPGO_KEEP_0__ 키를 요청 헤더에 전달합니다.

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

• Organization 역할 — 전체 조직에 걸쳐 키의 기본적인 권한을 정의합니다 (예: org_admin, org_member).
• App 역할 — 선택적 앱별 권한 (예: app_admin, app_developer, app_uploader, app_reader).

만약 API 키가 명시적인 역할 바인딩을 가지고 있다면 만 해당 바인딩 만 허용된 권한 검사에 평가됩니다. 키 소유자의 개인 권한은 키에 상속되지 않습니다.

주의

역할 바인딩이 없는 키는 legacy 모드 기반 시스템으로 돌아갑니다 (read, upload, write, all이러한 모드는 사용되지 않음 — RBAC 역할 대신 사용하십시오.

조직 생성 권한

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

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

• API 키는 org.create __CAPGO_KEEP_0__ 키는 global_permissions.
• API 키는 현재 조직 범위의 org_admin 또는 org_super_admin 새로운 __CAPGO_KEEP_0__ 키는
• New API keys do not receive org.create 기본적으로 활성화합니다. 조직 생성을 허용합니다. RBAC API 키를 داش보드에서 생성하거나 편집할 때.
• 기존에 쓰기 가능한 조직 관리자/슈퍼 관리자 API 키는 기존 통합을 위해 백업되었습니다. org.create 기존 통합이 조직을 계속 생성할 수 있도록 하기 위해.

API 키가 조직을 생성할 때, Capgo은 자동으로 새로 생성된 조직에 API 키를 assign합니다. 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 조직 생성에만 적용됩니다. 조직을 삭제하는 경우에는 대상 조직에 대한 삭제 권한이 필요하며, 일반적으로 __CAPGO_KEEP_1__을 통해 org_super_admin.

Secure (Hashed) Keys

__CAPGO_KEEP_1__ 생성 시 서버는 키 자료를 생성하고 평문 키 값을 한 번만 반환합니다. 해시만 저장됩니다. 이는:

• __CAPGO_KEEP_2__ 평문 키 생성 후 다시 추출할 수 없습니다. 생성 시 새로운 평문 키 (한 번만 표시)와 저장된 해시를 업데이트하는 새 키를 생성합니다.
• 해시된 키는 프로덕션 환경에서 권장됩니다.
• 일부 조직은 org 정책을 통해 해시된 키를 강제합니다.

__CAPGO_KEEP_3__ enforce_hashed_api_keys __CAPGO_KEEP_0__ (만료)

__CAPGO_KEEP_4__ 키는 선택적 만료 날짜를 가질 수 있습니다. 만료된 키는 허용 체크層에서 거부됩니다.

__CAPGO_KEEP_5__

Organization policies can enforce:

• 필수 만료 (require_apikey_expiration) — All new keys must have an expiry.
• 최대 TTL (max_apikey_expiration_days) — The expiry cannot be further than N days from now.

보안 최선의 실천

1. 최소 권한 원칙: 가장 제한적인 역할 assign하여 __CAPGO_KEEP_0__ still integration을 function하도록 하세요.
2. 정기적인 회전: API keys를 regenerate feature를 사용하여 정기적으로 rotate하세요.
3. 안전한 저장소: API 키를 안전하게 저장하고 버전 관리에 포함시키지 마세요.
4. Hashed Key 사용: 프로덕션 통합을 위해 안전한 (해시된) 키를 생성하세요.
5. 만료일 설정: 임시 또는 CI/CD 액세스에 사용되는 키에 항상 만료일을 설정하세요.
6. 권한 제한: 최소 권한의 역할을 가진 특정 앱에 키를 제한하세요.

일반적인 사용 사례

1. CI/CD 통합: 특정 앱에 키를 제한하고 app_uploader 또는 app_developer 역할 및 만료일 설정
2. 배포 자동화: 사용자 지정 키에 키를 사용하세요. app_developer 배포 자동화 스크립트를 위한 역할
3. 모니터링 도구: 사용자 지정 키에 키를 사용하세요. app_reader 외부 모니터링 통합을 위한 역할
4. 관리자 접근: 관리자 도구를 위한 역할을 사용하는 것을 자제하세요. org_admin 관리자 도구
5. : 특정 앱에 제한된 키를 사용하여 최소한의 역할을 사용하세요.세 번째-party 통합
6. 기업 설정: 신뢰할 수 있는 자동화가 조직을 생성하기 위해 필요한 경우에만 사용하세요. org_admin 또는 org_super_admin RBAC 키 org.create trusted automation

Keep going from API Keys

만약 __CAPGO_KEEP_0__ Keys API Keys 그것을 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login @capgo/capacitor-social-login for the implementation detail in @capgo/capacitor-social-login, @capgo/capacitor-passkey implementation 세부 사항을 위해 @capgo/capacitor-passkey @capgo/capacitor-native-biometric implementation 세부 사항을 위해 @capgo/capacitor-native-biometric 두 단계 인증 두 단계 인증의 implementation 세부 사항, 그리고 SSO (기업) SSO (기업)의 implementation 세부 사항.