Access Control Reference

Capgo 사용 역할 기반 접근 제어 (RBAC) 각 팀원들이 할 수 있는 것을 관리하는 데 사용됩니다. 역할은 범위에 따라 분류됩니다. 범위 — 조직 전체에서 단일 패키지까지.

관리자 대시보드에서 멤버 관리를 위한 시각적인_walkthrough를 보려면 조직.

---

역할 범위

각 역할은 특정 리소스에 접근할 수 있는지 결정하는 범위에 속합니다.

범위	적용	예시 사용 사례
단체	단체 전체 및 모든 앱	동료 창업주가 Super Admin; 회계 담당자가 Billing Manager
앱	단일 앱 및 채널	단일 앱에 근무하는 계약자가 App Developer
채널	단일 앱 내의 채널	채널 staging 채널
패키지	A single __CAPGO_KEEP_0__ version	A reviewer needs read access to one specific __CAPGO_KEEP_0__

A member can hold __CAPGO_KEEP_1__ one __CAPGO_KEEP_2__ per __CAPGO_KEEP_3__ target — for example, one org __CAPGO_KEEP_2__, one __CAPGO_KEEP_2__ on App A, and a different __CAPGO_KEEP_2__ on App B.

---

Organization __CAPGO_KEEP_2__

These __CAPGO_KEEP_2__ are assigned when inviting a member. They grant access across the entire organization.

__CAPGO_KEEP_2__	Internal __CAPGO_KEEP_4__	__CAPGO_KEEP_5__
Super __CAPGO_KEEP_6__	org_super_admin	Owner와 같은 권한. 조직 삭제, 결제 관리, 앱 전송 포함 모든 권한. 자동으로 조직 생성자에게 부여됨.
관리자	org_admin	전체 관리 — 멤버, 앱, 채널 관리. 조직 삭제, 결제 업데이트, 앱 전송, Super Admin 승격 불가.
결제 관리자	org_billing_admin	결제 전용 접근: 결제 정보, 청구서, 결제 감사 로그만 볼 수 있음. 앱 또는 멤버에 대한 접근 불가.
멤버	org_member	조직 권한 매트릭스

권한 매트릭스

최고 관리자	권한 매트릭스 섹션	권한	관리자	결제 매니저	멤버
org.read	조직 보기	✅	✅	✅	✅
org.update_settings	조직 이름, 로고, 관리 이메일 편집	✅	✅	❌	❌
org.delete	조직 영구 삭제	✅	❌	❌	❌
org.read_members	멤버 목록 보기	✅	✅	❌	✅
org.invite_user	새 멤버 초대	✅	✅	❌	❌
org.update_user_roles	멤버 역할 변경 (관리자로 승격할 수 없음 — 역할 계층으로 차단)	✅	✅	❌	❌
org.read_billing	결제 정보 및 현재 플랜 보기	✅	✅	✅	❌
org.update_billing	결제 수단 및 플랜 업데이트	✅	❌	✅	❌
org.read_invoices	청구서 보기	✅	✅	✅	❌
org.read_audit	활동 로그 보기	✅	✅	❌	❌
org.read_billing_audit	billing 관련 감사 로그 보기	✅	✅	✅	❌

주석

조직 역할은 앱, 채널 및 배치 역할의 하위 계층에서 모든 권한을 상속합니다. Super Admin 모든 것을 할 수 있는 App Admin 또는 채널 관리자 모든 앱과 채널에서 할 수 있습니다.

---

앱 역할

단일 애플리케이션에 제한됩니다. 팀원 한 명이 단일 애플리케이션에만 작업해야 할 때 사용합니다.

역할	내부 이름	설명
애플리케이션 관리자	app_admin	단일 애플리케이션에 대한 전체 제어 — 채널, 장치, 애플리케이션 내의 사용자 역할. 애플리케이션 삭제 또는 전송은 조직 수준의 작업입니다.
애플리케이션 개발자	app_developer	배포 패키지 업로드, 장치 관리, 네이티브 빌드 트리거, 채널 설정 업데이트. 삭제, 애플리케이션 설정 변경, 채널 생성은 허용되지 않습니다.
애플리케이션 업로드	app_uploader	읽기 전용 + 새로운 배포 패키지 버전 업로드
애플리케이션 리더	app_reader	읽기 전용 — 통계, 패키지, 채널, 로그, 장치.
앱 미리보기	app_preview	Organization- 및 앱에 바인딩된 미리보기 CI 라이프 사이클: 패키지를 업로드하고 미리보기 채널을 생성하세요. 그 채널을 생성하면 자동으로 라이프 사이클 권한이 그 채널에만 부여됩니다.

앱 권한 매트릭스

권한	설명	앱 관리자	앱 개발자	앱 업로더	앱 리더
app.read	앱 상세 정보, 통계 및 메타데이터를 보기	✅	✅	✅	✅
app.update_settings	설정 편집	✅	❌	❌	❌
app.read_bundles	업로드 된 패키지 목록 보기	✅	✅	✅	✅
app.upload_bundle	새 패키지 버전 업로드	✅	✅	✅	❌
app.create_channel	새 채널 만들기	✅	❌	❌	❌
app.read_channels	채널 목록 보기	✅	✅	✅	✅
app.read_logs	업데이트 전송 로그 보기	✅	✅	✅	✅
app.manage_devices	장치Assign, Override, 또는 unlink	✅	✅	❌	❌
app.read_devices	장치 목록 보기	✅	✅	✅	✅
app.build_native	자연 클라우드 빌드 트리거	✅	✅	❌	❌
app.read_audit	앱 수준 활동 로그 보기	✅	✅	✅	✅
app.update_user_roles	앱 범위 역할 assignments 관리	✅	❌	❌	❌
bundle.delete	패키지 삭제	✅	❌	❌	❌

Note

app.delete and app.transfer are org-level operations — only org_super_admin can perform them, regardless of app-level roles.

App Preview permission set

Use App Preview (app_preview) for an organization- and app-bound CI key that manages a PR preview lifecycle without broad app or organization-wide access.

The app_preview binding은 다음 앱 수준 권한만 부여합니다:

권한	허용
app.read	선택한 앱을 읽습니다
app.read_bundles	업로드된 패키지를 읽습니다
app.upload_bundle	패키지를 업로드합니다
app.create_channel	채널을 생성합니다

App Preview 키가 채널을 생성할 때, Capgo은 자동으로 새로운 채널에 대한 자식 channel_preview 권한

허용	__CAPGO_KEEP_0__
channel.read	채널을 생성한 키를 읽으십시오.
channel.promote_bundle	키가 업로드한 채널에 해당 채널의 업로드된 패키지를 설정합니다.
channel.delete	해당 채널을 삭제합니다.

그리고 app_preview 유지합니다. app.read, 키는 선택한 앱에서 채널 메타데이터를 열거할 수 있습니다. 자동 자식 바인딩은 키가 생성하지 않은 채널에 대해 생명 주기 수정을 허용하지 않습니다. 관리 경계입니다. 키가 생성하지 않은 채널에 대해 생명 주기 수정을 허용하지 않습니다.

Capgo은 각 채널과 업로드된 패키지를 생성한 App Preview 키가 기록합니다. 따라서 App Preview 키는 필요로 하는 각 비공개 미리보기 채널을 생성할 수 있으며, 자신의 패키지를 승격시키고, 해당 채널과 패키지를 원자적으로 삭제할 수 있습니다. 그러나 기존 기본/메인 채널, 다른 미리보기 키의 채널, 다른 키의 패키지에 대해 이러한 작업을 수행할 수 없습니다. channel delete --delete-bundle포함하지 않습니다.

, 장치 또는 역할 관리 app.update_settings, device or role management, channel.update_settings, channel.rollback_bundle강제 장치 관리, 또는 일반 bundle.delete.

주의

모든 App Preview 바인딩은 선택한 앱의 소유 기관과 연결되어 있습니다. 역할은 기관 전체 역할을 생략합니다. 역할을 취소하거나 만료하면 키의 유효한 라이프 사이클 접근 권한이 제거됩니다.

---

채널 역할

단일 채널에만 적용됩니다. 특정 릴리스 채널에 대한 목표 접근 권한을 제공하기 위해 유용합니다.

주의

채널 역할은 현재 __CAPGO_KEEP_0__ 및 __CAPGO_KEEP_1__를 통해만 사용할 수 있습니다. API 및 CLI를 통해만 사용할 수 있습니다. — 대시보드에서 Assign 하기 위한 UI가 없습니다. channel_preview 은 예외입니다: Capgo는 App Preview 키가 채널을 생성할 때 자동으로 생성합니다. 대시보드에서 채널 권한 우선순위 채널 권한 우선순위

역할	내부 이름	설명
채널 관리자	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	채널 활동 로그 보기	✅	✅	❌

---

롤 배포

단일 버전으로 제한된 역할입니다. 거의 사용되지 않습니다. 대부분의 팀은 앱 수준의 역할을 사용합니다.

주의

현재 버전에서 롤 배포는 사용 가능합니다. API과 CLI을 통해만 사용 가능합니다. __CAPGO_KEEP_0__과 __CAPGO_KEEP_1__을 통해만 사용 가능합니다.

역할	내부 이름	설명
패키지 관리자	bundle_admin	특정 패키지를 읽고, 업데이트, 삭제할 수 있습니다.
패키지 뷰어	bundle_reader	특정 패키지에 대한 읽기 전용 접근

---

채널 권한 오버라이드 (대시보드)

대시보드에서 채널 접근 권한은 기본적으로 사용자의 앱 역할에 의해 결정됩니다. 더 세부적인 제어를 원하시면 사용자 또는 그룹에 대한 특정 채널 권한을 오버라이드할 수 있습니다. 사용자 또는 그룹에 대한 특정 채널 권한을 오버라이드할 수 있습니다.

기본 설정은 앱의 접근 탭에서 사용자 옆에 있는 채널 권한 버튼(보호기호)으로 클릭합니다. Organization — 채널 권한을 재정의하는 방법 채널 권한을 재정의하는 방법에 대한 시각적인_walkthrough를 참조하십시오.

재정의 가능한 권한

권한	설명	기본 동작
읽기	채널과 현재 버블을 보십시오.	Inherited from app role
기록	채널에 할당된 패키지 기록을 확인하세요	Inherited from app role
패키지 연결	채널에 활성화된 패키지를 설정하거나 변경하세요	Inherited from app role

권한 설정 방법

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

이것은 예를 들어, 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)

실제 작동 방식:

• 한 관리자 기관 수준의 관리자는 모든 앱에서 앱 관리자가 할 수 있는 모든 것을 할 수 있습니다. 한 앱 관리자
• 특정 앱의 앱 관리자는 해당 앱의 모든 채널에서 채널 관리자가 할 수 있는 모든 것을 할 수 있습니다. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ __CAPGO_KEEP_3__
• An 애플리케이션 개발자 can do everything an 애플리케이션 업로더 can, plus more.

The hierarchy only flows downward — a channel_admin never gains org-level permissions, even if they also hold an app-level role.

---

그룹

대신에 사용자별로 역할을 assign하는 대신, 그룹 그룹에 역할을 assign하고 그룹의 모든 멤버가 자동으로 그 역할을 상속합니다.

그룹이 어떻게 작동하는가

• 그룹은 한 개의 조직에 속합니다. 다중 조직을跨越할 수 없습니다.
• 그룹은 어떤 범위에서든 역할 바인딩을 보유할 수 있습니다.org, app, channel, 또는 bundle. 예를 들어, 그룹은 App A에 App Developer 역할을 assign하고 App A의 App Developer 역할을 할당할 수 있습니다. 채널 관리자 __CAPGO_KEEP_0__ staging App B의 채널에서
• 사용자의 권한이 평가될 때, 그룹 구성원십은 투명하게 해결됩니다. 그룹 중 하나가 필요한 권한을 부여하면 접근이 허용됩니다.
• 사용자는 여러 그룹에 속할 수 있습니다, 모든 그룹의 권한이 누적됩니다.
• 그룹 기반 권한은 사용자 주체 에만 적용됩니다. API 키는 그룹 역할을 상속하지 않습니다.

그룹 사용하기

시나리오	그룹이 없는 경우	그룹이 있는 경우
3개의 앱에 대해 5명의 QA 엔지니어가 개발자 권한을 필요로 함	15개의 개별 역할 바인딩	1개의 그룹 + 3개의 역할 바인딩
QA 팀에 누군가가 합류함	3개의 역할 바인딩을 수동으로 추가함	그룹에 추가함
QA 팀에 누군가가 탈퇴함	3개의 역할 바인딩을 수동으로 제거함	그룹에서 제거함

Managing groups via API

모든 그룹 엔드포인트는 인증이 필요하고 __CAPGO_KEEP_0__ 하위에 제공됩니다. /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>"

주의

그룹에 역할 assign 하려면 API를 사용하세요. principal_type: "group" 그룹 UUID를 설정하세요. principal_id 역할 assign 하기

---

Assigning roles via API

그룹에서 역할을 assign 하려면 __CAPGO_KEEP_0__를 사용하세요.

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	관리자
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"
  }'

---

역할 assign via CLI

조직 목록

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

멤버 목록

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

주의

CLI은 현재 멤버 목록을 지원합니다. 멤버를 초대하거나 역할을 변경하기 위해서는 API 엔드포인트를 사용하세요.

---

사용자 정의 역할

내장 역할은 대부분의 팀 구조를 커버합니다. 사용자 정의 역할 생성은 우리의 로드맵에 있습니다 — 만약 팀이 이 기능을 필요로 한다면 우리에게 연락해 주세요.이 기능을 우선순위로 처리하는 데 직접적으로 도움이 될 것입니다.

Access Control Reference에서 계속 진행하세요.

Access Control Reference를 사용하여 대시보드와 __CAPGO_KEEP_0__ 작업을 계획하고 있다면, __CAPGO_KEEP_0__ Overview와 연결하세요. __CAPGO_KEEP_0__ Overview API Overview에서 구현 세부 정보를 확인하세요. API Overview for the implementation detail in API Overview, __CAPGO_KEEP_0__ 키 __CAPGO_KEEP_0__ 키 API 키 구현 세부 사항에 대한 API 키 기기 구현 세부 사항에 대한 기기, 및 묶음 구현 세부 사항에 대한 묶음.