Kunci API

Kunci API menggunakan role-based access control (RBAC). Sebuah kunci dapat memiliki role tingkat organisasi, app-scoped bindings, atau keduanya. Setiap app binding akan tetap terhubung dengan organisasi pemilik app tersebut. Untuk prinsip least privilege, batasi kunci hanya pada app tertentu alih-alih memberikan role tingkat organisasi.

Di mana pengelolaan kunci API?

Buka Pengaturan > Organisasi > Kunci API di console.capgo.app/settings/organization/api-keys.

Halaman ini menampilkan dua bagian:

• Kunci RBAC — Key dengan role yang ditentukan (direkomendasikan). Key ini menggunakan sistem permission berbasis role terbaru.
• Kunci Lama — Key lama yang menggunakan sistem berbasis mode sederhana (read, upload, write, all) tanpa penugasan role.

Cara membuat API key baru?

1. Klik ”+” tombol di bagian atas tabel RBAC keys.

2. Isi Informasi Key:

   • Name (wajib) — Label deskriptif untuk key (contohnya, “CI/CD Deploy” atau “Monitoring Read-Only”).
   • Buat secure key (opsional) — Jika dicentang, key akan di-hash di sisi server. Plain-text key hanya akan ditampilkan satu kali setelah dibuat dan tidak bisa dilihat lagi nanti.
   • Atur tanggal kedaluwarsa (opsional) — Pilih tanggal kedaluwarsa kunci. Beberapa organisasi mewajibkan masa berlaku kunci melalui kebijakan mereka.

3. Pilih scope key:

   • Akses seluruh organisasi — Pilih Role organisasi untuk menentukan izin dasar di seluruh organisasi. Role yang tersedia tergantung pada level role Anda:
     • Tidak ada — Tanpa akses ke seluruh organisasi.
     • Member — Akses baca dasar ke organisasi.
     • Admin — Akses administratif penuh ke organisasi dan semua aplikasinya.
   • Akses khusus aplikasi — Aktifkan Batasi key ini hanya untuk aplikasi tertentu. Setiap binding aplikasi tetap terhubung ke organisasi pemiliknya; mode ini hanya menghilangkan peran RBAC tingkat organisasi.

4. Jika key perlu membuat organisasi melalui API publik, aktifkan Izinkan pembuatan organisasi.

   Ini menambahkan permission global org.create . Key ini juga memerlukan binding tingkat organisasi. org_admin atau org_super_admin binding. Di dashboard, pilih Admin membuat org_admin binding. Saat kunci ini membuat organisasi baru, Capgo secara otomatis menetapkan kunci tersebut sebagai Super Admin di organisasi baru tersebut.

5. Untuk memberikan akses aplikasi:

   • Saat Batasi kunci ini ke aplikasi tertentu diaktifkan, pilih organisasi di bawah Organisasi untuk memfilter aplikasi untuk menampilkan aplikasinya. App binding yang dipilih tetap terhubung dengan organisasi pemiliknya; filter ini tidak memberikan akses ke seluruh organisasi.
   • Klik ”+ Tambah App”, pilih satu atau lebih aplikasi, lalu berikan role ke masing-masing:
     • App Reader — Akses read-only ke aplikasi.
     • App Uploader — Bisa upload bundle baru.
     • Developer Aplikasi — Bisa upload bundle, kelola device, trigger native build, dan atur setting channel.
     • Admin Aplikasi — Akses penuh ke aplikasi.
     • Pratinjau Aplikasi — Preview lifecycle CI/CD: upload bundle dan buat preview channel. Channel tersebut hanya menerima hak lifecycle otomatis berbasis channel khusus untuk key ini.

6. Klik “Create”.

7. Jika Anda mencentang Buat key yang aman, modal akan menampilkan key dalam bentuk plain-text. Copy it immediately — key tidak bisa dilihat lagi setelah modal ditutup.

Gunakan App Preview key untuk workflow preview

Gunakan Pratinjau Aplikasi untuk CI yang membuat preview channel sementara dan non-publik, upload dan promote bundle, lalu menghapus channel serta bundle tersebut. Key ini tidak memiliki akses lifecycle ke channel default atau main yang sudah ada.

1. Buat key RBAC dan aktifkan Batasi key ini untuk aplikasi tertentu.
2. Di bawah Organisasi untuk memfilter aplikasi, pilih organisasi untuk melihat aplikasinya; setiap aplikasi yang dipilih tetap terhubung dengan organisasinya.
3. Hanya tambahkan aplikasi yang digunakan untuk preview deployment.
4. Pilih Pratinjau Aplikasi untuk setiap aplikasi yang dipilih.
5. Buat key yang aman, atur tanggal kedaluwarsa jika perlu, dan simpan di CI secret manager Anda.

Mode khusus-aplikasi-terpilih ini tidak menggunakan role tingkat organisasi; mode ini akan tidak menghapus asosiasi organisasi. Setiap app_preview binding tetap terbatas pada aplikasi yang dipilih dan organisasi pemilik aplikasi tersebut.

Berikan	Izin dan batasan akses
app_preview pada aplikasi yang dipilih	app.read, app.read_bundles, app.upload_bundle, dan app.create_channel.
Otomatis channel_preview binding	Saat key ini membuat channel, Capgo secara otomatis memberikan key tersebut channel.read, channel.promote_bundle, dan channel.delete hanya untuk channel itu saja.

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

Capgo juga mencatat App Preview key mana yang mengunggah bundle. Key tersebut hanya bisa mengatur bundle miliknya sendiri pada setiap preview channel yang dibuatnya dan dapat menghapus pasangan tersebut secara bersamaan. Key ini tidak mendapatkan channel binding untuk channel default atau main yang sudah ada, channel yang dibuat oleh preview key lain, atau bundle milik key lain.

Untuk job CI pada umumnya, gunakan nama channel unik per pull request:

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --delete-bundle \
  --success-if-not-found

Untuk channel baru, bundle upload --channel membuat channel, mengunggah bundle, dan melakukan promosi dalam satu alur. Perintah terakhir menggunakan rute cleanup atomik yang terbatas: hanya berhasil jika key tersebut memiliki preview channel dan bundle terkait yang tidak dibagikan. Pratinjau Aplikasi masih tidak memiliki akses umum bundle.delete, sehingga tidak bisa menghapus bundle sembarang.

Peringatan

Gunakan channel baru yang pr-<number> tidak publik. Jangan masukkan --default, --self-assign, opsi rollout, atau --delete-linked-bundle-on-upload ke workflow ini. Sebuah Pratinjau Aplikasi key tidak bisa mempromosikan, menghapus, atau mengubah channel default/main yang ada, channel milik preview key lain, atau bundle milik key lain. Mencabut atau membuat app binding kedaluwarsa juga menghapus akses lifecycle efektif key tersebut.

Lihat Referensi kontrol akses untuk batas lengkapnya.

Cara mengelola (edit) key API?

Klik ikon kunci inggris (Kelola) pada kunci RBAC apa pun di daftar. Ini akan membuka halaman detail kunci di mana Anda dapat:

• Mengubah nama kunci.
• Perbarui peran organisasi.
• Aktifkan atau nonaktifkan Izinkan pembuatan organisasi saat kunci memiliki peran organisasi Admin.
• Tambah, hapus, atau ubah peran per-app.

Klik “Simpan Perubahan” setelah selesai.

Cara regenerasi kunci API?

Untuk regenerasi nilai secret dari kunci API, klik ikon refresh (Regenerate) pada kunci apa pun di daftar.

Dialog konfirmasi akan muncul. Setelah konfirmasi:

• Untuk kunci aman (hashed): Kunci plain-text baru akan dibuat dan ditampilkan sekali di modal. Segera salin kunci tersebut.
• Untuk kunci teks biasa: Nilai key akan dibuat ulang di sisi server.

Semua integrasi yang menggunakan nilai key lama akan langsung berhenti berfungsi.

Cara menghapus key API?

Klik ikon sampah (Delete) pada key apa pun di daftar. Konfirmasi penghapusan di dialog.

Key langsung dicabut — semua request yang menggunakannya akan gagal.

Kunci lama

Jika Anda melihat key di Kunci Lama section (key tanpa role assignment), ini menggunakan sistem izin berbasis mode lama (read, upload, write, all). Key ini masih berfungsi tetapi tidak mendapatkan manfaat dari izin RBAC yang lebih detail.

Legacy keys dapat dibuat ulang dan dihapus dari daftar, tetapi tidak dapat diedit untuk menambah role RBAC. Kami menyarankan untuk membuat key RBAC baru dan menghapus legacy keys jika memungkinkan.

Jika Anda perlu mengelola legacy keys secara langsung, Anda tetap bisa mengaksesnya di console.capgo.app/dashboard/apikeys. Halaman ini sudah deprecated dan akan dihapus pada update mendatang.

Lanjutkan dari API Keys

Jika Anda menggunakan Kunci API 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.