API Kunci

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

Menggunakan kunci API

Pakai header autentikasi yang dokumentasi oleh endpoint. Untuk permintaan kunci API, authorization Diterima:

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

Beberapa endpoint juga menerima kunci header khusus. Channel __CAPGO_KEEP_0__ Channels API __CAPGO_KEEP_0__ authorization atau gunakan salah satu header untuk otomatisasi saluran pratinjau. capgkeyHak Akses RBAC

Bab berjudul “Hak Akses RBAC”

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app or API, you assign roles at two levels:

• – Menentukan hak akses dasar kunci di seluruh organisasi (misalnya, atau org_admin Peran Aplikasi org_member).
• – Hak akses per-aplikasi (misalnya, , atau app_admin, app_developer, app_uploader, app_readerJika kunci __CAPGO_KEEP_0__ memiliki pengikat peran eksplisit, app_preview).

If an API key has explicit role bindings, hanya ikatan-ikatan yang di evaluasi untuk pengecekan izin. Kunci pemilik pribadi tidak diwarisi oleh kunci.

Automasi saluran pratinjau

Ikatan app_preview hanya ke aplikasi pratinjau untuk CI yang membuat saluran pratinjau sementara, tidak publik, 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 organisasi yang menguasai aplikasi. app_id adalah UUID internal aplikasi, bukan identifikasi aplikasi publik yang digunakan oleh perintah CLI (misalnya, com.example.app). Ikatan tetap terikat organisasi bahkan ketika kunci tidak memiliki peran organisasi-wide.

Peran aplikasi app_preview termasuk hanya app.read, app.read_bundles, app.upload_bundleWhen itu membuat channel, __CAPGO_KEEP_0__ secara otomatis menambahkan app.create_channel. When that key creates a channel, Capgo automatically adds a channel_preview retains channel.read, channel.promote_bundle, jadi ini bukan isolasi channel baca yang ketat: kunci itu mungkin dapat menelusuri metadata channel dalam aplikasi yang dipilih. Batasan binding otomatis hanya membatasi channel.delete mutasi siklus hidup

app_preview ke channel yang dibuat oleh kunci itu. app.read__CAPGO_KEEP_0__ merekam kunci App Preview yang mengunggah setiap bundle. Kunci itu hanya dapat mempromosikan bundle sendiri ke setiap channel preview yang dibuatnya. Kunci itu tidak memiliki akses siklus hidup channel untuk channel default/main yang sudah ada, channel yang dibuat oleh kunci preview lain, atau bundle milik kunci lain. Untuk alur kerja ini, lewati dan jangan pernah menggunakan Gunakan

Capgo records the App Preview key that uploaded each bundle. The key can promote only its own bundle to each preview channel it creates. It has no channel lifecycle access to an existing default/main channel, a channel created by another preview key, or another key’s bundle. For this workflow, omit public . --default.

. Ketika kunci membuat channel, __CAPGO_KEEP_0__ secara otomatis menambahkan binding pada channel yang baru saja dibuat. Binding anak itu hanya berlaku untuk channel yang dibuat oleh kunci itu. Kunci itu dapat menelusuri metadata channel dalam aplikasi yang dipilih, tetapi tidak dapat mengubahnya. Kunci itu hanya dapat mempromosikan bundle sendiri ke setiap channel preview yang dibuatnya. Kunci itu tidak memiliki akses siklus hidup channel untuk channel default/main yang sudah ada, channel yang dibuat oleh kunci preview lain, atau bundle milik kunci lain. Untuk alur kerja ini, lewati dan jangan pernah menggunakan Gunakan channel delete <preview-channel> <public-app-id> --delete-bundle untuk membersihkan. Ini adalah rute membersihkan yang atomik, memeriksa kepemilikan; hanya menghapus kanal pratinjau dan paket terkait yang dipanggil. app_preview tidak memberikan hak umum bundle.delete.

Untuk pengaturan dashboard dan contoh lengkap CLI, lihat Gunakan Kunci Pratinjau Aplikasi untuk alur kerja pratinjau.

Catatan

Kunci tanpa pengikatan peran akan kembali ke sistem berbasis mode (read, upload, write, all) yang sudah usang — gunakan peran RBAC saja.

Izin pembuatan organisasi

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

Izin ini berbeda dari peran role org/app normal karena organisasi baru belum ada ketika POST /organization/ dipanggil. Untuk membuat organisasi dengan kunci API:

• Kunci API harus mencakup org.create dalam global_permissions.
• Kunci API yang sama juga harus memiliki organisasi yang berlaku saat ini-skoped org_admin atau org_super_admin pengikat.
• Kunci API baru tidak menerima org.create oleh default. Aktifkan Izinkan membuat organisasi ketika membuat atau mengedit kunci RBAC API di dashboard.
• Kunci admin/super admin org yang dapat menulis/API sudah diisi ulang dengan org.create agar integrasi yang sudah ada dapat terus membuat organisasi.

Ketika sebuah API key membuat organisasi, Capgo secara otomatis mengasignkan key yang sama API sebagai org_super_admin pada organisasi yang baru saja dibuat. Hal ini memungkinkan integrasi mengelola organisasi yang baru saja dibuat tanpa perlu peran pengikat manual yang terpisah.

Jika Anda membuat API key melalui API, pastikan global_permissions termasuk 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 (Hashed) yang Aman

Ketika membuat kunci yang aman, server menghasilkan bahan kunci dan mengembalikan nilai teks biasa sekali. Hanya hash yang disimpan. Artinya:

• Kunci teks biasa tidak dapat diretrivekankan setelah pembuatan.
• Penggantian menghasilkan kunci teks sederhana baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Dianjurkan untuk menggunakan kunci yang di-hash dalam penggunaan produksi.

Beberapa organisasi mengenakan kunci yang di-hash melalui enforce_hashed_api_keys kebijakan org.

Kadaluarsa

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

Kebijakan organisasi dapat mengenakan:

• Wajib kadaluarsa (require_apikey_expiration — Semua kunci baru harus memiliki tenggat waktu.
• TTL Maksimum (max_apikey_expiration_days — Masa kadaluarsa tidak boleh lebih dari N hari dari sekarang.

Praktik Keamanan Terbaik

1. Prinsip Privilegi Terendah: Tugaskan peran yang paling restriktif yang masih memungkinkan integrasi Anda berfungsi
2. Penggantian Reguler: Ganti kunci API secara berkala menggunakan fitur regenerasi
3. Penyimpanan yang Aman: Simpan kunci API secara aman dan jangan pernah komitnya ke pengendalian versi
4. Gunakan Kunci Hashed: Buat kunci yang aman (dihash) untuk integrasi produksi
5. Atur Masa Kadaluarsa: Selalu tetapkan tanggal kadaluarsa pada kunci yang digunakan untuk akses sementara atau akses CI/CD
6. Keterbatasan Ruang Lingkup: Batasi kunci pada aplikasi tertentu dengan peran yang diperlukan minimal

Penggunaan Umum

1. Integrasi CI/CD: Buat kunci yang dikhususkan pada aplikasi tertentu dengan app_uploader atau app_developer peran, dan tetapkan tanggal kadaluarsa.
2. Saluran Pratinjau PR: Gunakan app_preview hanya pada aplikasi pratinjau atau aplikasi pratinjau yang hanya perlu mengunggah bundle, membuat saluran sementara, dan membersihkan saluran dan bundle sendiri secara atomik.
3. Automasi Pengaturan: Gunakan kunci dengan peran untuk skrip pengaturan otomatis. app_developer Alat Pemantauan
4. : Buat kunci dengan peran untuk integrasi pemantauan eksternal.Akses Administrator app_reader : Gunakan kunci dengan peran dengan hati-hati untuk alat administratif.
5. Integrasi Aplikasi Pihak Ketiga: Buat kunci yang terbatas pada aplikasi tertentu dengan peran yang diperlukan minimal. org_admin Pengaturan Organisasi
6. __CAPGO_KEEP_0____CAPGO_KEEP_0__
7. __CAPGO_KEEP_0__: Gunakan kunci RBAC dengan org_admin atau org_super_admin Kunci RBAC dengan hanya untuk otomatisasi yang dipercaya yang perlu membuat organisasi. org.create Lanjutkan dari __CAPGO_KEEP_0__ Kunci

Judul bagian “Lanjutkan dari API Kunci”

__CAPGO_KEEP_0__ Kunci API Keys @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-login-social untuk detail implementasi di @capgo/capacitor-login-social, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-login-social, untuk detail implementasi di @capgo/capacitor-login-social, untuk detail implementasi di @capgo/capacitor-login-social untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-native-biometric untuk detail implementasi di @capgo/capacitor-native-biometric, Autentikasi Dua Faktor untuk detail implementasi di Autentikasi Dua Faktor, dan SSO (Enterprise) untuk detail implementasi di SSO (Enterprise).