액세스 제어 레퍼런스

Capgo는 다음을 사용합니다 역할 기반 액세스 제어 (RBAC) 팀원별 권한을 관리합니다. 역할은 다음 범위에 따라 구분됩니다: 범위 — 조직 전체부터 개별 bundle까지.

대시보드에서 멤버를 관리하는 과정을 시각적으로 확인하려면 다음을 참조하세요: 조직.

---

역할 범위

모든 역할은 어떤 리소스에 접근 권한을 부여할지 결정하는 스코프에 속합니다.

지원 범위	적용 대상	사용 예시
조직	조직 전체와 모든 앱	공동 창업자에게는 Super Admin을, 회계 담당자에게는 Billing Manager 권한을 부여합니다.
앱	단일 앱 및 해당 채널	단일 앱을 담당하는 계약직은 App Developer 권한을 가집니다
채널	앱 내의 단일 채널	QA 엔지니어는 다음 항목만 관리합니다 staging 채널로 이동
Bundle	단일 Bundle 버전	리뷰어는 특정 릴리스에 대한 읽기 권한이 필요합니다

멤버는 다음을 가질 수 있습니다 스코프 대상당 하나의 역할 — 예: 하나의 조직 역할, App A에서의 역할, App B에서의 다른 역할

---

조직 역할

이 역할은 멤버를 초대할 때 지정되며, 조직 전체에 대한 액세스 권한을 부여합니다.

역할	내부 이름	설명
슈퍼 관리자	org_super_admin	Owner와 동등한 권한입니다. 조직 삭제, 결제 관리, 앱 이전을 포함한 전체 제어 권한을 가집니다. 조직 생성자에게 자동으로 부여됩니다.
Admin	org_admin	전체 관리 권한 — 멤버, 앱, 채널을 관리합니다. 조직 삭제, 결제 정보 업데이트, 앱 이전, 사용자를 Super Admin으로 승격하는 것은 할 수 없습니다.
결제 관리자	org_billing_admin	결제 전용 액세스: 결제 정보, 인보이스, 결제 감사 로그를 조회하고 업데이트할 수 있습니다. 앱이나 멤버에는 액세스할 수 없습니다.
멤버	org_member	조직 및 모든 앱에 대한 읽기 전용 권한.

조직 권한 매트릭스

권한	설명	슈퍼 관리자	Admin	결제 관리자	멤버
org.read	조직 보기	✅	✅	✅	✅
org.update_settings	조직 이름, 로고, 관리 이메일 수정	✅	✅	❌	❌
org.delete	조직 영구 삭제	✅	❌	❌	❌
org.read_members	멤버 목록 보기	✅	✅	❌	✅
org.invite_user	새 멤버 초대	✅	✅	❌	❌
org.update_user_roles	멤버 역할 변경 (Admin은 Super Admin으로 승격 불가 — 역할 계층에 의해 제한됨)	✅	✅	❌	❌
org.read_billing	결제 정보 및 현재 플랜 확인	✅	✅	✅	❌
org.update_billing	결제 수단 및 플랜 업데이트	✅	❌	✅	❌
org.read_invoices	인보이스 보기	✅	✅	✅	❌
org.read_audit	조직 활동 로그 보기	✅	✅	❌	❌
org.read_billing_audit	결제 관련 감사 로그 보기	✅	✅	✅	❌

참고

조직 역할은 계층 구조상 하위에 있는 app, channel, bundle 역할의 모든 권한을 상속받습니다. 슈퍼 관리자 이 역할은 앱 관리자 또는 채널 관리자 이 할 수 있는 모든 권한을 모든 앱과 채널에 대해 가집니다.

---

앱 역할

단일 앱에 한정된 권한입니다. 팀원이 조직 전체가 아닌 특정 앱에서만 작업해야 할 때 사용하세요.

역할	내부 이름	설명
앱 관리자	app_admin	앱에 대한 모든 권한을 가집니다. 채널, 디바이스, 앱 사용자 역할을 관리할 수 있습니다. 단, 앱 삭제나 이전은 불가능합니다(조직 레벨 작업).
앱 개발자	app_developer	bundle 업로드, 디바이스 관리, Native Build 실행, 채널 설정 변경이 가능합니다. 삭제, 앱 설정 변경, 채널 생성은 불가능합니다.
앱 업로더	app_uploader	읽기 권한 및 새로운 bundle 버전 업로드 권한을 가집니다.
앱 조회자	app_reader	읽기 전용 — 통계, bundle, 채널, logs, 디바이스 확인 가능.
앱 미리보기	app_preview	조직 및 앱에 종속된 Preview CI 라이프사이클: bundle을 업로드하고 preview 채널을 생성합니다. 채널 생성 시 해당 채널에 대해서만 라이프사이클 권한이 자동으로 부여됩니다.

앱 권한 매트릭스

권한	설명	앱 관리자	앱 개발자	앱 업로더	앱 조회자
app.read	앱 상세 정보, 통계 및 메타데이터 조회	✅	✅	✅	✅
app.update_settings	앱 설정 수정	✅	❌	❌	❌
app.read_bundles	업로드된 bundle 목록 조회	✅	✅	✅	✅
app.upload_bundle	새 bundle 버전 업로드	✅	✅	✅	❌
app.create_channel	새 channel 생성	✅	❌	❌	❌
app.read_channels	channel 조회	✅	✅	✅	✅
app.read_logs	업데이트 배포 로그 확인	✅	✅	✅	✅
app.manage_devices	디바이스 할당, 재지정 또는 연결 해제	✅	✅	❌	❌
app.read_devices	디바이스 목록 보기	✅	✅	✅	✅
app.build_native	Native Cloud Build 실행	✅	✅	❌	❌
app.read_audit	앱 단위 활동 로그 확인	✅	✅	✅	✅
app.update_user_roles	앱 범위 역할 할당 관리	✅	❌	❌	❌
bundle.delete	Bundle 삭제	✅	❌	❌	❌

참고

app.delete 및 app.transfer 은/는 조직 레벨 작업 —만 org_super_admin 수행할 수 있으며, 앱 레벨 역할과는 무관합니다.

App Preview 권한 세트

사용 앱 미리보기 (app_preview) 광범위한 앱 또는 조직 전체 접근 권한 없이 PR 프리뷰 라이프사이클을 관리하는 조직 및 앱에 바인딩된 CI 키용입니다.

이 app_preview 바인딩은 다음과 같은 앱 레벨 권한만 부여합니다:

권한	허용
app.read	선택한 앱 읽기
app.read_bundles	업로드된 bundle 읽기
app.upload_bundle	bundle 업로드
app.create_channel	channel 생성

App Preview key가 channel을 생성하면, Capgo은 해당 key에 대해 새 channel 전용 channel_preview child binding을 자동으로 부여합니다:

권한	허용
channel.read	key가 생성한 channel 읽기
channel.promote_bundle	해당 channel에 key 자체의 업로드된 bundle 설정
channel.delete	해당 channel 삭제

왜냐하면 app_preview 유지합니다 app.read, 이 키는 선택한 앱의 채널 메타데이터를 열거할 수 있습니다. 자동 하위 바인딩은 관리 경계입니다. 키가 생성하지 않은 채널에는 라이프사이클 변경 권한을 부여하지 않습니다.

Capgo는 각 채널을 생성하고 번들을 업로드한 프리뷰 키를 기록합니다. 따라서 App Preview 키는 필요한 비공개 프리뷰 채널을 직접 생성하고, 자신의 번들을 프로모션하며, 해당 채널과 번들을 Capgo와 함께 원자적으로 삭제할 수 있습니다. channel delete --delete-bundle; 기존 기본/메인 채널, 다른 프리뷰 키의 채널 또는 다른 키의 번들에는 이러한 작업을 수행할 수 없습니다.

포함하지 않는 항목은 app.update_settings, 디바이스 또는 역할 관리, channel.update_settings, channel.rollback_bundle, 강제 디바이스 관리 또는 일반 bundle.delete.

주의

모든 App Preview 바인딩은 선택한 앱의 소유 조직에 계속 연결됩니다. 이 역할은 조직 전체 역할을 포함하지 않지만, 조직 연결을 제거하지는 않습니다. 앱 바인딩을 해지하거나 만료시키면 해당 키의 유효한 라이프사이클 액세스가 제거됩니다.

---

채널 역할

단일 채널에 한정됩니다. 특정 릴리스 채널에 타겟팅된 권한을 부여할 때 유용합니다.

참고

Channel roles는 현재 API 및 CLI을 통해서만 사용 가능하며, 대시보드에서 직접 할당하는 UI는 제공되지 않습니다. channel_preview 은(는) 예외입니다: Capgo은 App Preview 키가 채널을 생성할 때 자동으로 생성합니다. 대시보드에서는 channel permission overrides를 사용하여 사용자별 채널 액세스 권한을 세부적으로 조정하세요.

역할	내부 이름	설명
채널 관리자	channel_admin	단일 채널에 대한 모든 권한: 설정, 번들 프로모션/롤백, 강제 디바이스 관리.
채널 뷰어	channel_reader	읽기 전용 — 현재 번들, 히스토리, 강제 디바이스, 감사 로그.
채널 미리보기	channel_preview	채널을 생성한 App Preview 키에 시스템적으로 할당됨: 읽기, 자체 번들 프로모션 및 해당 채널 삭제 가능.

채널 권한 매트릭스

권한	설명	채널 관리자	채널 뷰어	채널 미리보기
channel.read	채널 및 현재 번들 확인	✅	✅	✅
channel.update_settings	채널 설정 편집 (플랫폼 토글, 업데이트 정책 등)	✅	❌	❌
channel.delete	채널 삭제	✅	❌	✅
channel.read_history	번들 할당 이력 확인	✅	✅	❌
channel.promote_bundle	채널의 활성 번들 설정	✅	❌	✅
channel.rollback_bundle	이전 번들로 롤백	✅	❌	❌
channel.manage_forced_devices	특정 기기를 해당 채널로 강제 지정	✅	❌	❌
channel.read_forced_devices	강제 지정된 기기 목록 확인	✅	✅	❌
channel.read_audit	채널 활동 로그 확인	✅	✅	❌

---

Bundle 역할

단일 bundle 버전에만 적용됩니다. 대부분의 팀은 app 레벨의 role을 사용하므로 거의 필요하지 않습니다.

참고

Bundle role은 현재 API 및 CLI을 통해서만 사용 가능하며, dashboard에서 직접 할당할 수 있는 UI는 제공되지 않습니다.

역할	내부 이름	설명
Bundle 관리자	bundle_admin	특정 bundle의 읽기, 메타데이터 업데이트 및 삭제 권한
Bundle Viewer	bundle_reader	특정 bundle에 대한 읽기 전용 권한을 가집니다.

---

채널 권한 오버라이드 (Dashboard)

대시보드에서 채널 접근 권한은 기본적으로 사용자의 app role에 따라 결정됩니다. 더 세밀한 제어가 필요한 경우, 특정 채널 권한을 재정의할 수 있습니다. 사용자의 app role을 변경하지 않고도 사용자 또는 그룹별로 설정이 가능합니다.

재정의 설정은 앱의 액세스 탭에서 사용자 옆의 채널 권한 버튼(방패 아이콘)을 클릭하여 구성합니다. 자세한 내용은 조직 — 채널 권한 재정의하기 를 참고하여 단계별 가이드를 확인하세요.

오버라이드 가능한 권한

권한	설명	기본 동작
읽기	채널 및 현재 번들 확인	앱 역할에서 상속됨
기록	bundle 할당 기록 보기	앱 역할에서 상속됨
bundle 연결	채널의 활성 번들 설정 또는 변경	App 역할에서 상속됨

각 권한은 다음과 같이 설정할 수 있습니다:

• 기본값 — App 역할에서 상속 (기본값)
• 허용 — App 역할과 관계없이 명시적으로 허용
• 거부 — App 역할과 관계없이 명시적으로 차단

이를 통해 예를 들어 App Reader에게 App Developer 권한을 부여하지 않고도 staging 채널에 번들을 연결할 수 있는 권한을 줄 수 있습니다.

---

역할 계층 구조

역할은 계층 구조를 이룹니다. 상위 역할은 모든 권한을 상속받습니다. 하위 역할의 권한을 말이죠. 즉, org_admin 다음의 모든 권한을 가집니다 app_admin 할 수 있으며, 결과적으로 다음의 모든 작업을 수행할 수 있습니다. channel_admin 할 수 있는 모든 것을 할 수 있는 식입니다.

Super Admin (org_super_admin)
  └── Admin (org_admin)
        └── App Admin (app_admin)
              ├── App Developer (app_developer)
              │     └── App Uploader (app_uploader)
              │           └── App Reader (app_reader)
              ├── Bundle Admin (bundle_admin)
              │     └── Bundle Viewer (bundle_reader)
              └── Channel Admin (channel_admin)
                    └── Channel Viewer (channel_reader)

실제 작동 방식:

• 한 Admin 조직(org) 레벨에서 모든 권한을 가질 수 있습니다. 앱 관리자 조직 내 모든 앱에서 수행할 수 있습니다.
• 한 앱 관리자 특정 앱에서 모든 권한을 가집니다. 채널 관리자 해당 앱의 모든 채널에서 수행할 수 있습니다.
• 한 앱 개발자 다음 권한을 모두 포함합니다: 앱 업로더 수행할 수 있으며, 추가 권한도 가집니다.

계층 구조는 오직 하향식으로만 — channel_admin 적용됩니다. 앱 레벨 권한이 있더라도 조직 레벨 권한은 부여되지 않습니다.

---

그룹

사용자 개개인에게 역할을 할당하는 대신, 그룹을 생성하여 그룹에 역할을 할당할 수 있습니다. 그룹의 모든 멤버는 해당 역할을 자동으로 상속받습니다.

그룹 작동 방식

• 그룹은 다음의 소속입니다 단일 조직 — 여러 조직에 걸쳐 적용될 수 없습니다.
• 그룹은 다음 범위에서 역할을 지정할 수 있습니다: 모든 범위: org, app, channel 또는 bundle입니다. 예를 들어, 특정 그룹에 App A의 앱 개발자 역할과 App B의 채널 관리자 역할을 staging 채널에 각각 부여할 수 있습니다.
• 사용자의 권한을 평가할 때, 속한 모든 그룹 멤버십이 투명하게 확인됩니다. 그룹 중 하나라도 필요한 권한을 가지고 있다면 액세스가 허용됩니다.
• 사용자는 다음을 포함할 수 있습니다: 여러 그룹, 모든 그룹의 권한은 합산됩니다.
• 그룹 기반 권한은 다음 항목에만 적용됩니다: 사용자 principal — API 키는 그룹 역할을 상속받지 않습니다.

그룹 사용 시점

시나리오	그룹 미사용 시	그룹 사용 시
5명의 QA 엔지니어가 3개의 앱에 Developer 권한 필요	15개의 개별 역할 바인딩	1개 그룹 + 3개 역할 바인딩
QA 팀에 새로운 팀원 합류	3개의 역할 바인딩 수동 추가	그룹에 팀원 추가
QA 팀에서 팀원 이탈	3개의 역할 바인딩 수동 제거	그룹에서 팀원 제거

API를 통한 그룹 관리

모든 그룹 엔드포인트는 인증이 필요하며 다음 경로에서 제공됩니다 /private/groups.

그룹 목록

curl -X GET "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>"

필요 org.read_members 권한.

그룹 생성

curl -X POST "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Quality assurance engineers"
  }'

필요 org.update_user_roles 권한 (슈퍼 관리자 또는 관리자).

그룹 업데이트

curl -X PUT "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Updated description"
  }'

그룹 삭제

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>"

그룹을 삭제하면 해당 그룹에 할당된 모든 역할 바인딩도 함께 제거됩니다. 조직 내 멤버는 삭제되지 않습니다.

그룹 멤버 목록

curl -X GET "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>"

그룹에 멤버 추가

curl -X POST "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "<USER_UUID>" }'

사용자는 이미 조직의 멤버여야 합니다. 이미 존재하는 멤버를 추가하는 것은 아무런 동작도 수행하지 않습니다.

그룹에서 멤버 제거

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>/members/<USER_UUID>" \
  -H "authorization: <API_KEY>"

참고

그룹에 역할을 할당하려면 role bindings API의 principal_type: "group" 및 principal_id 값을 그룹 UUID로 설정하세요.

---

API를 통한 역할 할당

멤버 목록

curl -X GET "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "<ORG_ID>" }'

답변:

[
  {
    "uid": "user-uuid",
    "email": "alice@example.com",
    "image_url": "https://...",
    "role": "org_admin",
    "is_tmp": false
  }
]

멤버 초대하기

curl -X POST "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com",
    "invite_type": "org_admin"
  }'

허용되는 값: invite_type:

값	할당된 역할
org_super_admin	슈퍼 관리자
org_admin	Admin
org_billing_admin	결제 관리자
org_member	멤버

멤버 삭제하기

curl -X DELETE "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com"
  }'

---

CLI를 통한 역할 할당

조직 목록 조회

npx @capgo/cli organization list --apikey <API_KEY>

멤버 목록

npx @capgo/cli organization members <ORG_ID> --apikey <API_KEY>

참고

현재 CLI에서는 멤버 목록 조회만 지원합니다. 멤버 초대나 역할 변경을 프로그래밍 방식으로 수행하려면 상단의 API 엔드포인트를 사용하세요.

---

사용자 지정 역할

기본 제공되는 역할로 대부분의 팀 구조를 커버할 수 있습니다. 커스텀 역할 생성 기능은 로드맵에 포함되어 있으며, 만약 팀에 꼭 필요한 기능이라면 저희에게 문의해 주세요. 고객님의 사용 사례는 해당 기능의 우선순위를 결정하는 데 큰 도움이 됩니다.

Access Control Reference에서 계속 보기

사용 중이라면 액세스 제어 레퍼런스 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 구현 세부 사항은 API 키에서 기기 구현 세부 사항은 기기에서, 그리고 번들 Bundles의 구현 세부 사항은