Langsung ke konten

Kunci API

Kunci API menggunakan kontrol akses berbasis peran (RBAC). Kunci dapat memiliki peran untuk seluruh organisasi, binding yang dibatasi per aplikasi, atau keduanya. Setiap binding aplikasi tetap terkait dengan organisasi pemilik aplikasi tersebut. Untuk menerapkan least privilege, batasi kunci ke aplikasi tertentu alih-alih memberinya peran untuk seluruh organisasi.

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

Halaman ini menampilkan dua bagian:

  • Kunci RBAC — Kunci dengan peran yang ditugaskan (disarankan). Kunci ini menggunakan sistem izin berbasis peran yang baru.
  • Kunci Legacy — Kunci lama yang menggunakan sistem berbasis mode sederhana (read, upload, write, all) tanpa penugasan peran.
Halaman daftar API keys yang menampilkan bagian RBAC dan Legacy
  1. Klik ”+” tombol di bagian atas tabel kunci RBAC.

  2. Isi Informasi kunci:

    • Nama (wajib) — Label deskriptif untuk kunci (misalnya, “CI/CD Deploy” atau “Monitoring Read-Only”).
    • Buat kunci aman (opsional) — Jika dicentang, kunci akan di-hash di sisi server. Kunci plain-text hanya ditampilkan sekali setelah dibuat dan tidak dapat diambil kembali.
    • Atur tanggal kedaluwarsa (opsional) — Pilih tanggal setelah mana kunci berhenti berfungsi. Beberapa organisasi menerapkan kedaluwarsa wajib melalui kebijakan.
Formulir pembuatan API dengan nama, opsi kunci aman, dan masa kedaluwarsa
  1. Pilih cakupan kunci:

    • Akses seluruh organisasi — Pilih satu Peran organisasi untuk mendefinisikan izin dasar di seluruh organisasi. Peran yang tersedia bergantung pada level peran Anda:
      • Tidak ada — Tidak ada akses ke seluruh organisasi.
      • Anggota — Akses baca dasar ke organisasi.
      • Admin — Akses administratif penuh ke organisasi dan semua aplikasinya.
    • Akses khusus aplikasi — Aktifkan Batasi kunci ini untuk aplikasi yang dipilih. Setiap binding aplikasi tetap terhubung ke organisasi pemilik aplikasi tersebut; mode ini hanya mengabaikan peran RBAC tingkat organisasi.
  2. Jika kunci perlu membuat organisasi melalui API publik, aktifkan Izinkan membuat organisasi.

    Ini menambahkan izin global org.create Kunci juga memerlukan binding dengan cakupan organisasi org_admin atau org_super_admin binding. Di dashboard, memilih Admin membuat org_admin binding. Saat kunci ini membuat organisasi baru, Capgo secara otomatis menetapkan kunci tersebut sebagai Super Admin di organisasi baru itu.

  3. Untuk memberikan akses aplikasi:

    • Saat Batasi kunci ini untuk aplikasi tertentu diaktifkan, pilih organisasi di bawah Organisasi untuk memfilter aplikasi untuk menampilkan aplikasinya. Binding aplikasi yang dipilih tetap terkait dengan organisasi pemiliknya; filter ini tidak memberikan akses ke seluruh organisasi.
    • Klik ”+ Tambah Aplikasi”, pilih satu atau lebih aplikasi, lalu tetapkan peran untuk masing-masing:
      • App Reader — Akses hanya-baca ke aplikasi.
      • App Uploader — Dapat mengunggah bundle baru.
      • Developer Aplikasi — Dapat mengunggah bundle, mengelola perangkat, memicu native build, dan memperbarui pengaturan channel.
      • Admin Aplikasi — Akses penuh ke aplikasi.
      • Pratinjau Aplikasi — Pratinjau siklus hidup CI/CD: unggah bundle dan buat channel pratinjau. Channel menerima hak siklus hidup otomatis yang berjangkauan channel hanya untuk kunci ini.
  4. Klik “Buat”.

  5. Jika Anda mencentang Buat kunci aman, sebuah modal menampilkan key dalam teks biasa. Salin sekarang — tidak dapat diambil setelah modal ditutup.

Modal secret key API sekali pakai dengan tombol salin

Gunakan kunci App Preview untuk alur kerja preview

Bagian berjudul “Gunakan key App Preview untuk alur kerja preview”

Gunakan Pratinjau Aplikasi untuk CI yang membuat channel preview sementara yang non-publik, mengunggah dan mempromosikan bundle, lalu menghapus channel dan bundle tersebut. Tidak memiliki akses lifecycle ke channel default atau main yang sudah ada.

  1. Buat key RBAC dan aktifkan Batasi key ini ke aplikasi tertentu.
  2. Di bawah Organisasi untuk memfilter aplikasi, pilih organisasi untuk menampilkan aplikasinya; setiap aplikasi yang dipilih tetap terkait dengan organisasi pemiliknya.
  3. Tambahkan hanya aplikasi yang digunakan untuk deployment pratinjau.
  4. Pilih Pratinjau Aplikasi untuk setiap aplikasi yang dipilih.
  5. Buat kunci yang aman, atur tanggal kedaluwarsa jika diperlukan, dan simpan di CI secret manager Anda.

Mode hanya-aplikasi-yang-dipilih ini mengabaikan peran tingkat organisasi; tidak tidak menghapus asosiasi organisasi. Setiap app_preview binding tetap dibatasi pada aplikasi yang dipilih dan organisasi pemilik aplikasi tersebut.

Beri izinPermissions and boundary
app_preview pada aplikasi yang dipilihapp.read, app.read_bundles, app.upload_bundle, dan app.create_channel.
Otomatis channel_preview bindingSaat kunci ini membuat channel, Capgo secara otomatis memberikan kunci channel.read, channel.promote_bundle, dan channel.delete hanya untuk channel tersebut.

app_preview mempertahankan app.read, sehingga kunci dapat mengenumerasi metadata channel di aplikasi yang dipilih. Binding anak otomatis adalah manajemen batas: tidak memberikan mutasi lifecycle untuk channel yang tidak dibuat oleh kunci tersebut.

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

Untuk job CI yang umum, gunakan nama channel unik per pull request:

Jendela terminal
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 mempromosikannya dalam satu alur. Perintah terakhir menggunakan route cleanup atomik yang sempit: hanya berhasil jika key memiliki preview channel dan bundle terkait yang tidak dibagikan. Pratinjau Aplikasi masih belum memiliki umum bundle.delete, sehingga tidak dapat menghapus bundle sembarangan.

Lihat Referensi kontrol akses untuk batas lengkapnya.

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

  • Ubah kunci nama.
  • Perbarui peran organisasi.
  • Aktifkan atau nonaktifkan Izinkan membuat organisasi ketika kunci memiliki peran organisasi Admin.
  • Tambahkan, hapus, atau ubah peran per-aplikasi.

Klik “Simpan Perubahan” setelah selesai.

halaman edit kunci API dengan pengaturan peran saat ini

Untuk membuat ulang nilai rahasia kunci API, klik ikon refresh (Regenerate) pada kunci mana pun di daftar.

Dialog konfirmasi akan muncul. Setelah dikonfirmasi:

  • Untuk kunci aman (ter-hash): Kunci teks polos baru akan dibuat dan hanya ditampilkan sekali dalam modal. Salin segera.
  • Untuk kunci biasa: Nilai kunci akan dibuat ulang di sisi server.

Integrasi apa pun yang menggunakan nilai kunci lama akan berhenti berfungsi segera.

Konfirmasi pembuatan ulang kunci API

Klik ikon tempat sampah (Hapus) pada kunci mana pun di daftar. Konfirmasi penghapusan di dialog.

Kunci dicabut segera — permintaan apa pun yang menggunakannya akan gagal.

Dialog konfirmasi penghapusan kunci API

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

Legacy keys dapat di-regenerate dan dihapus dari daftar, tetapi tidak dapat diedit untuk menambahkan role RBAC. Kami merekomendasikan untuk membuat key RBAC baru dan menghapus legacy keys jika memungkinkan.

Jika Anda perlu mengelola legacy keys secara langsung, Anda masih dapat mengaksesnya di console.capgo.app/dashboard/apikeys. Halaman ini sudah tidak didukung dan akan dihapus dalam pembaruan mendatang.

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.