Referensi kontrol akses

Capgo menggunakan kontrol akses berbasis peran (RBAC) untuk mengatur izin setiap anggota tim. Role diatur berdasarkan scope — mulai dari seluruh organisasi hingga ke satu bundle saja.

Untuk panduan visual cara mengelola member di dashboard, lihat Organisasi.

---

Cakupan role

Setiap role memiliki scope yang menentukan resource mana saja yang bisa diakses.

Scope	Berlaku untuk	Contoh penggunaan
Organisasi	Seluruh org dan semua app-nya	Co-founder Anda menjadi Super Admin; akuntan Anda menjadi Billing Manager
App	Satu aplikasi dan channel-nya	Kontraktor yang mengerjakan satu aplikasi mendapat peran App Developer
Channel	Satu channel di dalam aplikasi	QA engineer hanya mengelola staging channel
Bundle	Satu versi bundle tunggal	Reviewer butuh akses baca ke satu rilis spesifik

Seorang anggota bisa memiliki satu peran per target scope — contohnya, satu peran org, satu peran di App A, dan peran berbeda di App B.

---

Role organisasi

Peran ini diberikan saat mengundang anggota. Peran ini memberikan akses ke seluruh organisasi.

Peran	Nama internal	Deskripsi
Super Admin	org_super_admin	Setara Owner. Kontrol penuh termasuk menghapus org, mengelola billing, dan transfer apps. Diberikan otomatis ke pembuat org.
Admin	org_admin	Administrasi penuh — kelola members, apps, channels. Tidak bisa menghapus org, update billing, transfer apps, atau mempromosikan user ke Super Admin.
Manajer Penagihan	org_billing_admin	Akses khusus billing: lihat dan update info billing, invoice, dan billing audit logs. Tidak ada akses ke apps atau members.
Member	org_member	Akses baca-saja ke organisasi dan semua aplikasinya.

Matriks izin organisasi

Izin	Deskripsi	Super Admin	Admin	Manajer Penagihan	Member
org.read	Lihat organisasi	✅	✅	✅	✅
org.update_settings	Edit nama, logo, dan email manajemen org	✅	✅	❌	❌
org.delete	Hapus organisasi secara permanen	✅	❌	❌	❌
org.read_members	Lihat daftar anggota	✅	✅	❌	✅
org.invite_user	Undang anggota baru	✅	✅	❌	❌
org.update_user_roles	Ubah role anggota (Admin tidak bisa mempromosikan ke Super Admin — dibatasi hierarki role)	✅	✅	❌	❌
org.read_billing	Lihat info billing dan paket saat ini	✅	✅	✅	❌
org.update_billing	Update metode pembayaran dan paket	✅	❌	✅	❌
org.read_invoices	Lihat invoice	✅	✅	✅	❌
org.read_audit	Lihat log aktivitas organisasi	✅	✅	❌	❌
org.read_billing_audit	Lihat audit log khusus billing	✅	✅	✅	❌

Catatan

Role organisasi mewarisi semua permission dari role app, channel, dan bundle di bawahnya dalam hierarki. Sebuah Super Admin bisa melakukan semua yang bisa dilakukan Admin Aplikasi atau Admin Channel di seluruh aplikasi dan channel.

---

Peran aplikasi

Terbatas pada satu app saja. Gunakan ini jika anggota tim hanya boleh mengerjakan satu app, bukan seluruh organisasi.

Role	Nama internal	Deskripsi
Admin Aplikasi	app_admin	Kontrol penuh atas satu aplikasi — channel, device, dan role pengguna untuk aplikasi tersebut. Tidak bisa menghapus atau mentransfer aplikasi (itu operasi tingkat organisasi).
Developer Aplikasi	app_developer	Upload bundle, kelola device, trigger native build, dan update pengaturan channel. Tidak bisa menghapus, mengubah pengaturan aplikasi, atau membuat channel baru.
App Uploader	app_uploader	Akses baca + upload versi bundle baru.
App Reader	app_reader	Read-only — stats, bundle, channel, logs, dan device.
Pratinjau Aplikasi	app_preview	Preview lifecycle CI yang terikat pada organisasi dan aplikasi: upload bundle dan buat preview channel. Membuat channel tersebut otomatis memberikan hak lifecycle hanya untuk channel itu.

Matriks izin aplikasi

Izin	Deskripsi	Admin Aplikasi	Developer Aplikasi	App Uploader	App Reader
app.read	Lihat detail, statistik, dan metadata app	✅	✅	✅	✅
app.update_settings	Edit pengaturan app	✅	❌	❌	❌
app.read_bundles	Lihat daftar bundle yang di-upload	✅	✅	✅	✅
app.upload_bundle	Upload versi bundle baru	✅	✅	✅	❌
app.create_channel	Buat channel baru	✅	❌	❌	❌
app.read_channels	Lihat channel	✅	✅	✅	✅
app.read_logs	Lihat log pengiriman update	✅	✅	✅	✅
app.manage_devices	Tetapkan, override, atau unlink device	✅	✅	❌	❌
app.read_devices	Lihat daftar device	✅	✅	✅	✅
app.build_native	Picu native cloud build	✅	✅	❌	❌
app.read_audit	Lihat log aktivitas level app	✅	✅	✅	✅
app.update_user_roles	Kelola assignment role per app	✅	❌	❌	❌
bundle.delete	Hapus bundle	✅	❌	❌	❌

Catatan

app.delete dan app.transfer adalah operasi level org — hanya org_super_admin yang bisa melakukannya, terlepas dari role di level app.

Set izin App Preview

Gunakan Pratinjau Aplikasi (app_preview) untuk CI key yang terikat ke organisasi dan app guna mengelola lifecycle PR preview tanpa akses luas ke seluruh app atau organisasi.

Panduan app_preview binding ini hanya memberikan izin di level app berikut:

Izin	Kegunaan
app.read	Baca app yang dipilih
app.read_bundles	Baca bundle yang di-upload
app.upload_bundle	Upload bundle
app.create_channel	Buat channel

Saat App Preview key membuat channel, Capgo secara otomatis memberikan key tersebut child channel_preview binding hanya untuk channel baru:

Izin	Mengizinkan
channel.read	Baca channel yang dibuat oleh key
channel.promote_bundle	Set bundle yang di-upload oleh key tersebut pada channel itu
channel.delete	Hapus channel tersebut

Karena app_preview mempertahankan app.read, key tersebut dapat mencantumkan metadata channel pada app yang dipilih. Automatic child binding adalah manajemen boundary: key tidak memberikan izin mutasi lifecycle untuk channel yang tidak dibuat oleh key tersebut.

Capgo mencatat preview key yang membuat setiap channel dan mengunggah setiap bundle. Oleh karena itu, App Preview key dapat membuat setiap non-public preview channel yang dibutuhkan, mempromosikan bundle miliknya sendiri, dan menghapus channel serta bundle tersebut secara atomik dengan channel delete --delete-bundle; hal tersebut tidak dapat dilakukan pada channel default/utama yang sudah ada, channel dari preview key lain, atau bundle milik key lain.

Ini tidak mencakup app.update_settings, manajemen device atau role, channel.update_settings, channel.rollback_bundle, manajemen forced-device, atau bundle.delete.

Peringatan

Setiap App Preview binding tetap terhubung ke organisasi pemilik app yang dipilih. Role ini tidak menyertakan role tingkat organisasi; namun tidak menghapus asosiasi organisasi. Mencabut atau mengekspirasi app binding akan menghapus akses lifecycle efektif dari key tersebut.

---

Role channel

Terbatas pada satu channel saja. Berguna untuk memberikan akses terarah ke channel rilis tertentu.

Catatan

Channel roles saat ini tersedia hanya melalui API dan CLI — belum ada UI untuk mengaturnya di dashboard. channel_preview adalah pengecualian: Capgo membuatnya secara otomatis untuk App Preview key saat key tersebut membuat channel. Di dashboard, gunakan override izin channel untuk mengatur akses channel per user secara lebih detail.

Role	Nama internal	Deskripsi
Admin Channel	channel_admin	Kontrol penuh satu channel: pengaturan, promote/rollback bundle, dan kelola forced devices.
Viewer Channel	channel_reader	Read-only — bundle saat ini, riwayat, forced devices, dan audit log.
Preview Channel	channel_preview	Diberikan otomatis ke App Preview key pembuat channel: baca, promote bundle sendiri, dan hapus channel tersebut.

Matriks izin channel

Izin	Deskripsi	Admin Channel	Pemantau Channel	Pratinjau Channel
channel.read	Lihat channel dan bundle saat ini	✅	✅	✅
channel.update_settings	Edit pengaturan channel (toggle platform, kebijakan update…)	✅	❌	❌
channel.delete	Hapus channel	✅	❌	✅
channel.read_history	Lihat riwayat assignment bundle	✅	✅	❌
channel.promote_bundle	Set bundle aktif pada channel	✅	❌	✅
channel.rollback_bundle	Roll back ke bundle sebelumnya	✅	❌	❌
channel.manage_forced_devices	Paksa perangkat tertentu ke channel ini	✅	❌	❌
channel.read_forced_devices	Lihat daftar perangkat yang dipaksa	✅	✅	❌
channel.read_audit	Lihat log aktivitas channel	✅	✅	❌

---

Role Bundle

Terbatas pada satu versi bundle saja. Jarang dibutuhkan — kebanyakan tim lebih memilih menggunakan role di level app.

Catatan

Bundle roles saat ini tersedia hanya melalui API dan CLI — belum ada UI untuk mengaturnya di dashboard.

Role	Nama internal	Deskripsi
Admin Bundle	bundle_admin	Baca, update metadata, dan hapus bundle tertentu.
Bundle Viewer	bundle_reader	Akses baca-saja ke bundle tertentu.

---

Override izin channel (Dashboard)

Di dashboard, akses channel secara default ditentukan oleh role app pengguna. Untuk kontrol yang lebih granular, Anda bisa melakukan override izin channel tertentu per user atau grup tanpa mengubah role app mereka.

Override dikonfigurasi dari tab Akses app dengan mengklik tombol channel permissions (ikon shield) di samping user. Lihat Organisasi — Menimpa izin channel untuk panduan visualnya.

Izin yang dapat diubah

Izin	Deskripsi	Perilaku default
Baca	Melihat channel dan bundle saat ini	Diwarisi dari role app
Riwayat	Melihat riwayat penugasan bundle	Diwarisi dari role app
Hubungkan bundle	Atur atau ubah bundle aktif pada channel	Diwarisi dari role app

Setiap permission dapat diatur ke:

• Default — inherit dari role app (default)
• Izinkan — berikan akses secara eksplisit, terlepas dari role app
• Tolak — blokir secara eksplisit, terlepas dari role app

Dengan ini Anda dapat, misalnya, memberikan kemampuan kepada App Reader untuk mengasosiasikan bundle pada staging channel tanpa harus mempromosikannya menjadi App Developer.

---

Hierarki Role

Role membentuk sebuah hierarki. Role induk mewarisi semua permission dari role anaknya. Ini berarti org_admin bisa melakukan semua yang bisa dilakukan app_admin yang kemudian dapat melakukan semua hal seperti channel_admin role berikutnya, dan seterusnya.

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)

Cara kerjanya secara praktis:

• Sebuah Admin di level org bisa melakukan semua yang bisa dilakukan Admin Aplikasi bisa, di setiap aplikasi dalam organisasi.
• Sebuah Admin Aplikasi on a specific app can do everything a Admin Channel bisa, di setiap channel pada aplikasi tersebut.
• Sebuah Developer Aplikasi bisa melakukan semua yang dilakukan App Uploader bisa, ditambah fitur lainnya.

Hierarki ini hanya mengalir ke bawah — seorang channel_admin tidak akan mendapat izin level organisasi, meski mereka punya role di level app.

---

Grup

Daripada memberikan role ke tiap user satu per satu, Anda bisa membuat group dan memberikan role ke group tersebut. Setiap anggota group akan otomatis mewarisi role itu.

Cara kerja group

• Sebuah group termasuk dalam satu organisasi — tidak bisa mencakup beberapa org.
• Group dapat menyimpan role binding di scope apa pun: org, app, channel, atau bundle. Contohnya, sebuah group bisa diberi Developer Aplikasi role di App A dan Admin Channel role pada staging channel di App B.
• Saat izin user dievaluasi, semua keanggotaan group mereka akan diproses secara transparan. Jika salah satu group memberikan izin yang diperlukan, akses akan diberikan.
• Seorang user bisa tergabung dalam beberapa grup, dan izin dari semua grup bersifat akumulatif.
• Izin berbasis grup hanya berlaku untuk prinsipal pengguna — API keys tidak mewarisi role grup.

Kapan menggunakan grup

Skenario	Tanpa grup	Dengan grup
5 QA engineer butuh akses Developer ke 3 app	15 role bindings individual	1 grup + 3 role binding
Seseorang bergabung ke tim QA	Tambah 3 role binding secara manual	Tambahkan mereka ke grup
Seseorang keluar dari tim QA	Hapus 3 role binding secara manual	Hapus mereka dari grup

Mengelola grup via API

Semua endpoint grup memerlukan autentikasi dan tersedia di /private/groups.

List grup

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

Membutuhkan org.read_members izinnya.

Create a group

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

Membutuhkan org.update_user_roles permission (Super Admin atau Admin).

Update grup

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

Hapus grup

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

Menghapus grup juga akan menghapus semua role binding-nya. Anggota tidak akan dihapus dari organisasi.

Daftar anggota grup

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

Tambah anggota ke grup

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

User harus sudah menjadi anggota organisasi. Menambahkan anggota yang sudah ada tidak akan melakukan perubahan apa pun.

Hapus anggota dari grup

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

Catatan

Untuk memberikan role ke sebuah grup, gunakan role bindings API dengan principal_type: "group" dan principal_id set ke UUID grup tersebut.

---

Memberikan role via API

List member

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

Respons:

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

Undang anggota

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

Nilai yang diterima untuk invite_type:

Nilai	Role yang diberikan
org_super_admin	Super Admin
org_admin	Admin
org_billing_admin	Manajer Penagihan
org_member	Member

Hapus anggota

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

---

Menetapkan role via CLI

Daftar organisasi

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

Daftar anggota

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

Catatan

CLI saat ini baru mendukung daftar member. Untuk mengundang member atau mengubah role secara terprogram, gunakan endpoint API di atas.

---

Peran kustom

Role bawaan sudah mencakup sebagian besar struktur tim. Pembuatan custom role ada dalam roadmap kami — jika tim Anda membutuhkannya, hubungi kami. Use case Anda akan membantu kami memprioritaskan fitur ini.

Lanjutkan dari Access Control Reference

Jika Anda menggunakan Referensi kontrol akses untuk merencanakan operasi dashboard dan API, hubungkan dengan Ringkasan API untuk detail implementasi di API Overview, Pendahuluan untuk detail implementasi di Introduction, Kunci API untuk detail implementasi di API Keys, Perangkat untuk detail implementasi di Devices, dan Bundle untuk detail implementasi di Bundles.