API Kunci

API keys use role-based access control (RBAC). A key can have an organization-wide role, app-scoped bindings, or both. Every app binding remains associated with that app’s owning organization. For least privilege, restrict a key to selected apps instead of assigning an organization-wide role.

Dimana API kunci-kunci ini diatur?

Navigasikan ke Pengaturan > Organisasi > API Kunci-Kunci di console.capgo.app/pengaturan/organisasi/api-kunci.

Halaman ini menampilkan dua bagian:

• Kunci RBAC — Kunci-kunci dengan peran yang ditugaskan (direkomendasikan). Kunci-kunci ini menggunakan sistem izin berbasis peran baru.
• Kunci Legacy — Kunci-kunci yang lebih tua yang menggunakan sistem mode sederhana (read, upload, write, all) tanpa penugasan peran.

Bagaimana cara membuat kunci API baru?

1. Klik tombol ‘ ”+” ’ di atas tabel kunci RBAC.

2. Isi informasi kunci Informasi Kunci:

   • Nama (wajib) — Label deskriptif untuk kunci (misalnya, “Deploy CI/CD” atau “Monitoring Baca-Saja”).
   • Buat kunci aman (opsional) — Ketika dicentang, kunci di-hash di sisi server. Kunci teks biasa hanya ditampilkan satu kali Setelah pembuatan dan tidak dapat diperoleh lagi.
   • Pilih tanggal setelahnya key tidak berfungsi lagi. Beberapa organisasi mewajibkan pengaturan tanggal kadaluarsa melalui kebijakan. Form pembuatan __CAPGO_KEEP_0__ key dengan nama, opsi kunci aman, dan tanggal kadaluarsa

3. Akses organisasi secara keseluruhan

   • — Pilih peran organisasi untuk menentukan izin dasar di seluruh organisasi. Peran yang tersedia bergantung pada tingkat peran Anda sendiri: Tidak ada — Tidak ada akses organisasi secara keseluruhan.
     • Anggota Anggota — Tidak ada akses organisasi secara keseluruhan.
     • Tidak ada akses organisasi secara keseluruhan — Tidak ada akses organisasi secara keseluruhan. Akses baca dasar ke organisasi ini.
     • Akses Administrator Akses aplikasi hanya
   • Aktifkan Batasi akses kunci ini ke aplikasi yang dipilih. Setiap pengikat aplikasi tetap terkait dengan organisasi yang dimiliki aplikasi tersebut; mode ini mengabaikan hanya peran RBAC organisasi.Jika kunci perlu membuat organisasi melalui __CAPGO_KEEP_0__ publik, aktifkan

4. If the key needs to create organizations through the public API, enable Peran global ini ditambahkan..

   Kunci juga memerlukan peran organisasi yang dipasang org.create atau org_admin atau org_super_admin Mengikat. Di dashboard, memilih Pengguna Mengikat. Ketika kunci ini membuat organisasi baru, __CAPGO_KEEP_0__ secara otomatis menetapkan kunci sebagai Super Admin pada organisasi baru tersebut. org_admin binding. When this key creates a new organization, Capgo automatically assigns the key as Super Admin on that new organization.

5. Ketika

   • Mengikat kunci ini hanya untuk aplikasi yang dipilih diaktifkan, pilih organisasi di bawah Organisasi untuk memfilter aplikasi untuk menampilkan aplikasinya. Pengikat aplikasi yang dipilih tetap terkait dengan organisasinya; filter ini tidak memberikan akses organisasi secara keseluruhan. Klik
   • ”+ Tambahkan Aplikasi” Untuk mengikat aplikasi, pilih aplikasi di bawah Organisasi untuk memfilter aplikasi, lalu klik Tambahkan AplikasiPilih satu atau lebih aplikasi, kemudian tentukan peran untuk setiap:
     • Aplikasi Pembaca — Akses baca saja ke aplikasi.
     • Aplikasi Pengunggah — Dapat mengunggah bundle baru.
     • Aplikasi Pengembang — Dapat mengunggah bundle, mengelola perangkat, memicu build native, dan mengatur pengaturan saluran.
     • Aplikasi Administrator — Akses penuh ke aplikasi.
     • Aplikasi Pratinjau — Pratinjau siklus CI/CD: unggah bundle dan buat saluran pratinjau. Saluran ini menerima hak siklus otomatis, terbatas pada saluran, hanya untuk ini.

6. Klik Buat.

7. Jika Anda telah memeriksa Buat kunci yang amanModal menampilkan kunci teks biasa. Salin segera — tidak dapat diretrive setelah menutup modal.

Gunakan kunci App Preview untuk alur kerja pra-siarkan

Gunakan App Preview untuk CI yang membuat saluran pra-siarkan sementara, tidak publik, mengunggah dan mempromosikan paket, kemudian menghapus baik saluran maupun paket. Tidak memiliki akses ke siklus saluran default atau utama yang sudah ada.

1. Buatlah kunci RBAC dan aktifkan Batasi kunci ini hanya untuk aplikasi yang dipilih.
2. Di bawah Organisasi untuk menyaring aplikasi, pilih organisasi untuk menampilkan aplikasinya; setiap aplikasi yang dipilih tetap terkait dengan organisasinya.
3. Tambahkan hanya aplikasi atau aplikasi yang digunakan untuk preview deployment.
4. Pilih Penglihatan Aplikasi untuk setiap aplikasi yang dipilih.
5. Buatlah kunci yang aman, tentukan tanggal kedaluwarsa ketika perlu, dan simpan di manajer rahasia CI Anda.

Mode aplikasi yang dipilih ini mengabaikan peran organisasi secara keseluruhan; itu tidak Hapus hubungan organisasi. Setiap app_preview keterikatan tetap terkait dengan aplikasi yang dipilih dan organisasi pemilik aplikasi tersebut.

Ijin	Izin dan batasan
app_preview pada aplikasi yang dipilih	app.read, app.read_bundles, app.upload_bundle, dan app.create_channel.
Otomatis channel_preview keterikatan	Ketika kunci ini membuat saluran, Capgo secara otomatis memberikan kunci channel.read, channel.promote_bundle, dan channel.delete hanya untuk saluran tersebut saja.

app_preview tertahan app.readMungkin __CAPGO_KEEP_0__ juga merekam kunci App Preview yang mengunggah bundle. Kunci tersebut hanya dapat mengatur bundle sendiri pada setiap saluran pratinjau yang dibuatnya dan dapat membersihkan pasangan tersebut bersamaan. Namun, kunci tersebut tidak menerima ikatan saluran untuk saluran default atau utama yang sudah ada, saluran pratinjau yang dibuat oleh kunci pratinjau lain, atau bundle milik kunci lain. Pengaturan batas: tidak memberikan mutasi siklus hidup untuk saluran yang kunci tersebut tidak buat.

Mungkin Capgo juga merekam kunci App Preview yang mengunggah bundle. Kunci tersebut hanya dapat mengatur bundle sendiri pada setiap saluran pratinjau yang dibuatnya dan dapat membersihkan pasangan tersebut bersamaan. Namun, kunci tersebut tidak menerima ikatan saluran untuk saluran default atau utama yang sudah ada, saluran pratinjau yang dibuat oleh kunci pratinjau lain, atau bundle milik kunci lain.

Untuk pekerjaan CI biasa, gunakan nama saluran unik per permintaan pull:

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 saluran baru, bundle upload --channel Membuat saluran, mengunggah bundle, dan mempromosikannya dalam satu alur. Perintah terakhir menggunakan jalur pembersihan atomik yang sempit: perintah tersebut hanya berhasil ketika kunci tersebut memiliki saluran pratinjau dan bundle terkait yang tidak dibagikan. App Preview masih belum memiliki fitur umum bundle.deleteMungkin __CAPGO_KEEP_0__ juga merekam kunci App Preview yang mengunggah bundle. Kunci tersebut hanya dapat mengatur bundle sendiri pada setiap saluran pratinjau yang dibuatnya dan dapat membersihkan pasangan tersebut bersamaan. Namun, kunci tersebut tidak menerima ikatan saluran untuk saluran default atau utama yang sudah ada, saluran pratinjau yang dibuat oleh kunci pratinjau lain, atau bundle milik kunci lain.

Hati-hati

Pakai saluran baru yang tidak umum. pr-<number> Tidak boleh melewati --default, --self-assign, opsi peluncuran, atau --delete-linked-bundle-on-upload ke dalam alur kerja ini. Sebuah Pratinjau Aplikasi tidak dapat mempromosikan, menghapus, atau mengubah saluran default/main yang sudah ada, saluran pratinjau kunci lainnya, atau paket kunci lainnya. Mengambil kembali atau mengakhiri ikatan aplikasi juga menghapus akses kehidupan kunci yang efektif.

Lihat referensi Pengendalian Akses untuk batasan penuh.

Cara mengelola (mengedit) sebuah API kunci?

Klik ikon wrench di mana pun kunci RBAC di daftar. Ini membuka halaman detail kunci di mana Anda dapat:

• Mengubah nama kunci Mengupdate peran organisasi.
• Mengaktifkan atau menonaktifkan Mengizinkan pembuatan organisasi.
• ketika kunci memiliki peran organisasi Admin. Menambahkan, menghapus, atau mengubah peran organisasi
• izin peran aplikasi.

Klik “Simpan Perubahan” ketika selesai.

Bagaimana cara menghasilkan kembali kunci API?

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

Dialog konfirmasi akan muncul. Setelah mengkonfirmasi:

• Untuk Kunci (dihash) yang aman: Kunci teks biasa baru dihasilkan dan ditampilkan sekali dalam modal. Salinlah segera.
• Untuk kunci teks biasa: Nilai kunci dihasilkan ulang di server.

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

Bagaimana cara menghapus kunci API?

Klik ikon sampah (Hapus) pada kunci mana pun di daftar. Konfirmasi penghapusan dalam dialog. How to delete an __CAPGO_KEEP_0__ key?

Kunci tersebut dibatalkan segera — setiap permintaan yang menggunakan kunci tersebut akan gagal.

Kunci Legacy

Jika Anda melihat kunci di Kunci Legacy bagian (kunci tanpa penugasan peran), kunci tersebut menggunakan sistem izin berbasis mode yang lebih lama (”,). Kunci tersebut masih berfungsi, tetapi tidak mendapatkan manfaat dari RBAC hak istimewa izin.read, upload, write, allKunci Legacy dapat diulangi dan dihapus dari daftar, tetapi tidak dapat diedit untuk menambahkan peran RBAC. Kami merekomendasikan membuat kunci RBAC baru dan menghapus kunci Legacy ketika memungkinkan.

Jika Anda perlu mengelola kunci Legacy secara langsung, Anda masih dapat mengaksesnya di

console.__CAPGO_KEEP_0__.app/dashboard/apikeys console.capgo.app/dashboard/apikeysKunci Legacy dapat diulangi dan dihapus dari daftar, tetapi tidak dapat diedit untuk menambahkan peran RBAC. Kami merekomendasikan membuat kunci RBAC baru dan menghapus kunci Legacy ketika memungkinkan.

Teruskan dari API Kunci

Jika Anda menggunakan API Kunci untuk merencanakan dashboard dan API operasi, hubungkannya dengan API Ringkasan untuk detail implementasi di API Ringkasan, Pendahuluan untuk detail implementasi di Pendahuluan, API Kunci untuk detail implementasi di API Kunci, Perangkat untuk detail implementasi di Perangkat, dan Bundel untuk detail implementasi di Bundel.