Access Control Reference

Capgo는 역할 기반 접근 제어(RBAC)를 사용하여 각 팀원에게 할 수 있는 것을 관리합니다. 역할은 범위 — 조직 전체에서 단일 번들까지 scope

관리자 dashboard에서 멤버 관리를 위한 시각적인 워크숍을 참조하십시오. Organization.

---

권한 범위

권한 범위는 각 역할이 접근할 수 있는 리소스를 결정하는 범위입니다.

Scope	적용 대상	예시 사용 사례
Organization	전체 조직 및 모든 앱	동료 창업주에게 Super Admin; 회계 담당자에게 Billing Manager 권한을 부여합니다.
App	단일 앱과 그 채널들	단일 앱에 작업하는 계약자에게 App Developer가 부여됩니다.
채널	단일 앱 내의 단일 채널	QA 엔지니어가 단일 채널만 관리합니다. staging Bundle
단일 버전의 채널	리뷰어는 특정 릴리스에 대한 읽기 전용 접근권한이 필요합니다.	멤버는 scope target당 하나의 역할을 보유할 수 있습니다.

예를 들어, 하나의 조직 역할, App A의 역할, App B의 다른 역할. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__

---

조직 역할

회원 초대를 통해 할당되는 역할입니다. 조직 전체에 대한 접근 권한을 부여합니다.

역할	내부 이름	설명
슈퍼 관리자	org_super_admin	조직 생성자에게 자동으로 부여되는 소유권이 있는 역할. 조직 삭제, 계정 관리, 앱 전송 포함.
관리자	org_admin	회원, 앱, 채널 관리가 가능합니다. 조직 삭제, 계정 관리, 앱 전송, 사용자 슈퍼 관리자로 승격할 수 없습니다.
결제 관리자	org_billing_admin	결제에만 접근할 수 있습니다. 결제 정보, 청구서, 결제 감사 로그를 볼 수 있고, 수정할 수 있습니다. 앱 또는 회원에 대한 접근 권한이 없습니다.
회원	org_member	기관 및 모든 앱에 대한 읽기 전용 접근.

기관 권한 매트릭스

권한	설명	슈퍼 관리자	관리자	결제 관리자	회원
org.read	기관을 보는	✅	✅	✅	✅
org.update_settings	기관 이름, 로고, 관리 이메일 편집	✅	✅	❌	❌
org.delete	__CAPGO_KEEP_0__을 영구 삭제합니다.	✅	❌	❌	❌
org.read_members	__CAPGO_KEEP_1__ 회원 목록을 확인합니다.	✅	✅	❌	✅
org.invite_user	__CAPGO_KEEP_2__ 새로운 회원을 초대합니다.	✅	✅	❌	❌
org.update_user_roles	__CAPGO_KEEP_3__ (관리자도 Super Admin으로 승격할 수 없습니다. 역할 계층 구조로 인해 차단됩니다.)	✅	✅	❌	❌
org.read_billing	__CAPGO_KEEP_4__ 요금 정보 및 현재 플랜을 확인합니다.	✅	✅	✅	❌
org.update_billing	__CAPGO_KEEP_5__ 결제 방법 및 플랜을 업데이트 합니다.	✅	❌	✅	❌
org.read_invoices	__CAPGO_KEEP_6__ 청구서를 확인합니다.	✅	✅	✅	❌
org.read_audit	__CAPGO_KEEP_7__ 조직 활동 로그를 확인합니다.	✅	✅	❌	❌
org.read_billing_audit	__CAPGO_KEEP_8__ 요금 관련 감사 로그를 확인합니다.	✅	✅	✅	❌

__CAPGO_KEEP_10__

__CAPGO_KEEP_11__ 조직 역할은 앱, 채널 및 패키지 역할 아래에 있는 모든 권한을 상속합니다. 역할 계층 구조에서 상위 역할은 하위 역할의 모든 권한을 상속합니다. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ __CAPGO_KEEP_3__ __CAPGO_KEEP_4__ __CAPGO_KEEP_5__

---

__CAPGO_KEEP_6__

__CAPGO_KEEP_8__

__CAPGO_KEEP_9__	__CAPGO_KEEP_10__	__CAPGO_KEEP_11__
앱 관리자	app_admin	1개의 앱에 대한 전체 제어 — 채널, 장치, 사용자 역할. 앱 삭제 또는 전송은 불가능 (그것들은 조직 수준의 작업입니다).
앱 개발자	app_developer	번들 업로드, 장치 관리, 원시 빌드 트리거, 채널 설정 업데이트. 삭제, 앱 설정 변경, 채널 생성은 불가능합니다.
앱 업로더	app_uploader	읽기 권한 + 새로운 번들 버전 업로드.
앱 리더	app_reader	읽기 전용 — 통계, 번들, 채널, 로그, 장치.

앱 권한 매트릭스

설명	권한 매트릭스	앱 관리	앱 개발자	앱 업로드	앱 리더
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	__CAPGO_KEEP_0__ 목록 보기	✅	✅	✅	✅
app.build_native	__CAPGO_KEEP_0__ 네이티브 클라우드 빌드를 트리거합니다	✅	✅	❌	❌
app.read_audit	__CAPGO_KEEP_0__ 앱 수준 활동 로그를 봅니다	✅	✅	✅	✅
app.update_user_roles	__CAPGO_KEEP_0__ 앱 범위 역할 할당을 관리합니다	✅	❌	❌	❌
bundle.delete	__CAPGO_KEEP_0__ 번들을 삭제합니다	✅	❌	❌	❌

__CAPGO_KEEP_1__

app.delete __CAPGO_KEEP_2__ app.transfer __CAPGO_KEEP_3__ __CAPGO_KEEP_4__ — 단지 __CAPGO_KEEP_4__ 수행할 수 있습니다, 앱 수준 역할과 관계없이. org_super_admin __CAPGO_KEEP_5__

---

채널 역할

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

주의

현재 채널 역할은 __CAPGO_KEEP_0__ 및 __CAPGO_KEEP_1__에서만 사용할 수 있습니다. 채널 역할은 API 및 CLI에서만 사용할 수 있습니다. 대시보드에서 채널 역할을 assign하는 UI는 없습니다. 대신 채널 권한 오버라이드 대시보드에서 채널 권한 오버라이드 대시보드에서 채널 권한 오버라이드

채널 역할	내부 이름	설명
채널 관리자	channel_admin	채널 하나에 대한 전체 제어: 설정, 배포/롤백 패키지, 강제 장치 관리.
채널 뷰어	channel_reader	읽기 전용 — 현재 패키지, 기록, 강제 장치, 감사 로그.

채널 권한 매트릭스

권한	설명	채널 관리자	채널 뷰어
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	채널 활동 로그 보기	✅	✅

---

배포 역할

특정 버전의 배포에만 적용됩니다. 대부분의 팀은 앱 수준의 역할을 사용합니다.

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__ API와 CLI만을 통해 현재 역할을 할당할 수 있습니다. — 대시보드에서 역할을 할당하는 UI가 없습니다.

역할	내부 이름	설명
Bundle Admin	bundle_admin	특정 번들에 대해 읽기, 업데이트 메타데이터, 삭제할 수 있습니다.
Bundle Viewer	bundle_reader	특정 번들에 대한 읽기 전용 접근권한이 있습니다.

---

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

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

오버라이드 설정은 앱의 Access 탭에서 채널 권한 버튼 (보호기 아이콘)을 클릭하여 사용자 옆에 있습니다. 자세한 설명은 Organization — 채널 권한 오버라이드 에서 확인하실 수 있습니다.

오버라이드 가능한 권한

권한	설명	기본 동작
읽기	채널과 현재 번들 보기	앱 역할에서 상속
기록	번들 assignment 기록 보기	앱 역할에서 상속
번들 연관	채널에 현재 번들 설정 또는 변경	앱 역할에서 상속

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

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

이것은 예를 들어, App Reader에게 채널에서 패키지를 연관시킬 수 있는 권한을 부여하는 것을 허용합니다. staging 권한 계층

---

Section titled “권한 계층”

모든 권한을 상속합니다. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__의 자녀들 중 하나입니다. 따라서 __CAPGO_KEEP_0__는 org_admin __CAPGO_KEEP_0__를 할 수 있습니다. 따라서 __CAPGO_KEEP_1__는 app_admin __CAPGO_KEEP_1__도 할 수 있습니다. 따라서 __CAPGO_KEEP_1__는 channel_admin __CAPGO_KEEP_1__도 할 수 있습니다. 따라서 __CAPGO_KEEP_1__는

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_0__에서 관리자는 __CAPGO_KEEP_1__도 할 수 있습니다. 따라서 __CAPGO_KEEP_1__는 __CAPGO_KEEP_1__도 할 수 있습니다. 따라서 __CAPGO_KEEP_1__는 __CAPGO_KEEP_1__도 할 수 있습니다. 따라서 __CAPGO_KEEP_1__는
• __CAPGO_KEEP_1__도 할 수 있습니다. 따라서 __CAPGO_KEEP_1__는 App Admin __CAPGO_KEEP_0__의 특정 앱에서 __CAPGO_KEEP_0__가 할 수 있는 모든 것을 할 수 있습니다. Channel Admin __CAPGO_KEEP_0__의 모든 채널에서 __CAPGO_KEEP_1__가 할 수 있는 모든 것을 할 수 있습니다.
• __CAPGO_KEEP_1__ App Developer __CAPGO_KEEP_1__가 __CAPGO_KEEP_1__가 할 수 있는 모든 것을 할 수 있습니다, 더 많은 것을 할 수 있습니다. __CAPGO_KEEP_1__는 아래로만 흐릅니다. —

__CAPGO_KEEP_2__ __CAPGO_KEEP_2__ __CAPGO_KEEP_2__ channel_admin __CAPGO_KEEP_0__은 조직 수준의 권한을 얻지 못하며, 앱 수준의 역할을 보유하고 있더라도.

---

그룹

사용자별로 역할을 assign하는 대신, 그룹을 생성하여 역할을 그룹에 assign할 수 있습니다. 그룹 그룹에 역할을 assign하면 그룹의 모든 멤버가 자동으로 그 역할을 inherit합니다.

그룹의 작동 방식

• 그룹은 한 개의 조직에 속합니다. 다중 조직에 걸쳐서 span할 수 없습니다.
• 그룹은 역할 바인딩을 보유할 수 있습니다. 어떤 범위: org, app, channel, or bundle. 예를 들어, 그룹은 App A에 App Developer 역할과 App B의 channel에 Channel Admin 역할을 할당할 수 있습니다. 앱 개발자 역할 채널 관리자 사용자의 권한이 평가될 때, 그룹 소속이 모두 투명하게 해결됩니다. 사용자의 그룹 중 하나가 필요한 권한을 부여하면 접근이 허용됩니다. staging 사용자는
• 여러 그룹
• 에 속할 수 있으며, 그룹의 모든 권한이 누적됩니다. 그룹 기반 권한은에만 적용됩니다.
• Group-based permissions only apply to 사용자 원칙 — API 키는 그룹 역할을 상속하지 않습니다.

그룹 사용 시기

사례	그룹 미사용	그룹 사용
5 명의 QA 엔지니어가 3 개의 앱에 개발자 접근 권한이 필요합니다.	15 개의 개별 역할 바인딩	1 개의 그룹 + 3 개의 역할 바인딩
QA 팀에 누군가가 합류합니다.	3 개의 역할 바인딩을 수동으로 추가합니다.	그룹에 추가하세요
QA 팀에서 alguien이 떠남	3개의 역할 바인딩을 수동으로 제거하세요	그룹에서 제거하세요

API를 통해 그룹 관리하기

모든 그룹 엔드포인트는 인증이 필요하고 /private/groups.

그룹 목록

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

인증이 필요합니다 org.read_members __CAPGO_KEEP_0__.

그룹 만들기

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 __CAPGO_KEEP_0__ (슈퍼 관리자 또는 관리자).

그룹 업데이트

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 하려면 role bindings API를 사용하십시오. 그리고 principal_type: "group" and principal_id __CAPGO_KEEP_0__을 그룹 UUID로 설정합니다.

---

API를 통해 역할 assign합니다.

멤버 목록

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
  }
]

__CAPGO_KEEP_0__를 통해 멤버 초대

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"
  }'

---

CLI 역할 assign

조직 목록

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 를 통해 대시보드 및 API 연산을 계획하고 있다면, API Overview implementation 세부 정보를 위한 API 개요 소개 implementation 세부 정보를 위한 Introduction API 키 implementation 세부 정보를 위한 API 키 장치 implementation 세부 정보를 위한 Devices 번들 implementation 세부 정보를 위한 Bundles