Kunci API

Pengaturan siap dicopy dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.

Kunci API digunakan untuk mengautentikasi permintaan ke Capgo API. Kunci-kunci ini spesifik organisasi dan dapat diberi peran RBAC untuk kontrol akses yang halus. Setiap kunci juga dapat memiliki tanggal kadaluarsa opsional dan dapat dibuat sebagai kunci 'aman' (dihash) di mana nilai teks biasa hanya ditampilkan sekali.

Menggunakan kunci API

Gunakan header autentikasi yang dokumentasi oleh endpoint. Untuk permintaan kunci API-key, authorization diterima:

curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

Beberapa endpoint juga menerima kunci header khusus. The Saluran API menerima authorization atau capgkeyatau gunakan salah satu header tersebut untuk otomatisasi saluran pratinjau.

Izin Akses RBAC

Kunci API menggunakan sistem kontrol akses berdasarkan peran (RBAC) yang sama seperti akun pengguna. Ketika membuat atau mengelola kunci melalui aplikasi web atau API, Anda menetapkan peran pada dua tingkat:

Peran Organisasi — Menetapkan hak akses dasar kunci di seluruh organisasi (misalnya, org_admin atau org_member).
Peran Aplikasi – Izin aplikasi per aplikasi (misalnya, app_admin, app_developer, app_uploader, app_reader, or app_preview).

Jika sebuah API memiliki pengikat peran eksplisit, Jika kunci __CAPGO_KEEP_0__ memiliki pengikat peran eksplisit, Kunci tersebut dievaluasi untuk periksa izin. Izin pribadi pemilik kunci tidak diwariskan ke kunci tersebut.

Siaran Pra-Publikasi Channel

Pasang app_preview hanya ke aplikasi pratinjau untuk CI yang menciptakan saluran pratinjau sementara, tidak umum, mengunggah dan mempromosikan paket, kemudian menghapus keduanya.

{
  "name": "PR preview key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "app_preview",
      "scope_type": "app",
      "org_id": "<OWNING_ORG_UUID>",
      "app_id": "<APP_UUID>"
    }
  ]
}

org_id adalah UUID dari organisasi yang menguasai aplikasi. app_id adalah UUID internal dari rekaman aplikasi, bukan identifikasi aplikasi publik yang digunakan oleh perintah CLI (misalnya,” com.example.appKeterikatan tetap terikat pada organisasi bahkan ketika kunci tidak memiliki peran organisasi yang luas.

Level aplikasi app_preview termasuk hanya app.read, app.read_bundles, app.upload_bundle, dan app.create_channelSaat kunci tersebut membuat sebuah channel, Capgo secara otomatis menambahkan channel_preview Kunci Binding pada Channel Baru. Kunci Binding tersebut dapat digunakan oleh anak kunci. channel.read, channel.promote_bundledan channel.delete hanya untuk saluran yang kunci dibuat.

app_preview menyimpan app.read, sehingga ini bukan isolasi membaca saluran yang ketat: kunci mungkin menghitung metadata saluran dalam aplikasi yang dipilih. Batasan ikatan anak otomatis mutasi siklus hidup hanya untuk saluran yang kunci dibuat.

Capgo merekam kunci Pratinjau Aplikasi yang mengunggah setiap paket. Kunci dapat mempromosikan hanya paketnya sendiri ke setiap saluran pratinjau yang dibuatnya. Kunci tidak memiliki akses siklus hidup ke saluran default/main yang ada, saluran yang dibuat oleh kunci pratinjau lain, atau paket kunci lain. Untuk alur kerja ini, lewatkan public dan jangan pernah menggunakan --default.

Pakai channel delete <preview-channel> <public-app-id> --delete-bundle untuk membersihkan. Ini adalah jalur membersihkan pratinjau yang atomik, diperiksa kepemilikan; hanya menghapus saluran pratinjau dan paket terkait yang dipanggil. app_preview tidak memberikan hak umum bundle.delete.

Untuk setup dashboard dan contoh CLI yang lengkap, lihat Gunakan kunci App Preview untuk alur kerja pra-siaran.

Diagram yang menjelaskan bagaimana kunci RBAC API mengatur izin

Izin pembuatan organisasi

Membuat organisasi dengan kunci API sekarang menggunakan izin global eksplisit: org.create.

Saat ini, izin ini berbeda dari pengaturan peran org/app normal karena organisasi baru belum ada ketika} POST /organization/ digunakan. Untuk membuat organisasi dengan kunci API:

Kunci API harus termasuk org.create di global_permissions.
Kunci API yang sama harus juga memiliki organisasi yang berlaku saat ini org_admin atau org_super_admin binding.
Kunci API baru tidak menerima org.create Memungkinkan pembuatan organisasi Mengizinkan pembuatan organisasi Kunci API admin/super admin organisasi yang dapat menulis sudah diisi dengan
Admin organisasi yang dapat menulis/super admin API telah diisi ulang dengan org.create Integrasi yang sudah ada dapat terus membuat organisasi.

Saat sebuah API kunci membuat sebuah organisasi, Capgo secara otomatis mengasignasikan kunci yang sama sebagai API kunci. org_super_admin Pada organisasi yang baru dibuat. Ini memungkinkan integrasi mengelola organisasi yang baru saja dibuat tanpa perlu pengikat peran manual yang terpisah.

Jika Anda membuat kunci API melalui API, termasuk global_permissions bersama dengan pengikat admin organisasi:

{
  "name": "Provisioning key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "org_admin",
      "scope_type": "org",
      "org_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "global_permissions": ["org.create"]
}

org.create hanya berlaku untuk membuat organisasi. Menghapus organisasi masih memerlukan izin hapus pada organisasi target, biasanya melalui org_super_admin.

Kunci yang Aman (Ditimbun)

Mengapa membuat kunci yang aman, server menghasilkan bahan kunci dan mengembalikan nilai teks biasa sekali. Hanya sebuah hash disimpan. Ini berarti:

Kunci teks biasa tidak dapat diperoleh setelah pembuatan.
Regenerasi menghasilkan kunci teks baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
Kunci yang ditimbun disarankan untuk penggunaan produksi.

Beberapa organisasi mengenakan kunci hash melalui enforce_hashed_api_keys org kebijakan.

Kadaluarsa

Kunci dapat memiliki tanggal kadaluarsa opsional. Kunci yang telah kadaluarsa ditolak pada lapisan periksa izin.

Pengaturan kebijakan organisasi dapat mengenakan:

Wajib kadaluarsa (require_apikey_expiration) — Semua kunci baru harus memiliki kadaluarsa.
Maksimum TTL (max_apikey_expiration_days) — Kadaluarsa tidak dapat lebih dari N hari dari sekarang.

Praktik Keamanan Terbaik

Prinsip Privilegi Terendah: Tugaskan peran yang paling restriktif yang masih memungkinkan integrasi Anda berfungsi
Rotasi Teratur: Rotasi kunci API Anda secara berkala menggunakan fitur regenerasi
Penyimpanan Aman: Simpan kunci API secara aman dan jangan pernah komitnya ke pengembangan kontrol
Penggunaan Kunci Hashed: Buat kunci yang aman (dihash) untuk integrasi produksi
Penetapan Masa Berlaku: Selalu tetapkan tanggal berlaku pada kunci yang digunakan untuk akses sementara atau akses CI/CD
Penggunaan Restriksi Scope: Batasi kunci ke aplikasi tertentu dengan peran yang paling sedikit diperlukan

Kasus Penggunaan Umum

Pengintegrasian CI/CDBuat kunci yang terbatas pada aplikasi tertentu dengan app_uploader or app_developer peran, dan atur tanggal kadaluarsa.
Saluran Pratinjau PR: Use app_preview on only the preview app or apps when CI needs to upload a bundle, create a temporary channel, and atomically clean up its own channel and bundle.
Automasi PenggunaanGunakan kunci dengan app_developer Pengautomatan Pengembangan (Deployment Automation)
Alat PemantauanBuatlah kunci dengan app_reader fungsi untuk integrasi pemantauan eksternal.
Akses AdministratorIntegrasi Pihak Ketiga org_admin role sparingly for administrative tools.
Pengaturan Organisasi: Gunakanlah kunci dengan peran yang lebih rendah untuk pengaturan organisasi.
Provisi OrganisasiGunakan API Key org_admin or org_super_admin Kunci RBAC org.create hanya untuk otomatisasi yang dipercaya yang perlu membuat organisasi.

Halaman ini: API Keys

Jika Anda menggunakan __CAPGO_KEEP_0__ Keys Kunci API hubungkan dengan untuk merencanakan autentikasi dan aliran akun @capgo/capacitor-login Sosial Untuk detail implementasi di @capgo/capacitor-social-login, @capgo/capacitor-kunci akses Untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-native-biometric untuk detail implementasi di @capgo/capacitor-biometrik-nasional, Autentikasi dua faktor untuk detail implementasi dalam Autentikasi dua faktor, dan Single Sign-On (Enterprise) untuk detail implementasi dalam SSO (Enterprise).