API 키

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

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

Using an API key

API 키를 사용하는 방법 x-api-key __CAPGO_KEEP_0__ 키를 사용하는 방법

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

복사 authorization 요청 헤더도 지원되지만, JWT 토큰에만 주로 사용됩니다. UUID 형식의 API 키는 작동하지만, 모든 키 유형(secure/hashed 키 포함)에서 권장되는 헤더입니다. x-api-key RBAC 권한

RBAC 권한

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

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

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

보안 (해시) 키

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

평문 키 생성 후 다시 획득할 수 없습니다. 재생성은 새로운 평문 키 (한 번만 표시)와 저장된 해시를 업데이트합니다.
해시 키는 프로덕션 사용을 권장합니다.
일부 조직은 해시 키를 조직 정책을 통해 강제합니다.

만료 enforce_hashed_api_keys __CAPGO_KEEP_0__

__CAPGO_KEEP_1__

키는 선택적으로 만료일을 가질 수 있습니다. 만료된 키는 권한 확인 계층에서 거부됩니다.

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

필수 만료 (require_apikey_expiration) — 모든 새로운 키는 만료일이 있어야 합니다.
최대 TTL (max_apikey_expiration_days) — 만료일은 현재로부터 N일 이내로 설정할 수 없습니다.

보안 최적화

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

일반적인 사용 사례

CI/CD 통합: __CAPGO_KEEP_0__ 앱에 특정한 키를 생성하세요. app_uploader or app_developer 역할에 따라 키를 생성하고 만료일을 설정하세요.
배포 자동화: __CAPGO_KEEP_0__ 역할을 가진 키를 사용하여 자동화 배포 스크립트를 실행하세요. app_developer 모니터링 도구
: __CAPGO_KEEP_0__ 역할을 가진 키를 사용하여 외부 모니터링 통합을 생성하세요.관리자 접근 app_reader : __CAPGO_KEEP_0__ 역할을 가진 키를 사용하여 관리자 도구를 실행하세요.
or역할에 따라 키를 생성하세요. org_admin 배포 자동화
세 번째 파티 연동: 특정 앱에 대한 최소 권한으로 제한된 키를 생성합니다.