API Keys

Kopikan prompt pengaturan dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.

API kunci digunakan untuk menerapkan permintaan ke Capgo API. Kunci khusus organisasi dan dapat diberikan 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

Pakai header autentikasi yang dokumentasi oleh endpoint. Untuk permintaan kunci API- authorization diakui:

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

Beberapa endpoint juga menerima kunci header khusus. Saluran-saluran API Menerima authorization atau capgkey; gunakan salah satu header untuk otomatisasi saluran pratinjau.

Hak Akses Berdasarkan Peran (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).
context HTML teks fragmen dari string UI Capgo yang lebih panjang (kunci induk `alternatives_cta_questions`). Halaman/area: Halaman perbandingan alternatif live-update Capacitor. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman alternatives.astro. Simpan istilah produk/brand dan developer Capgo secara tepat. Kunci pesan `alternatives_cta_questions` (Alternatif CTA Pertanyaan). | Teks fragmen HTML dari string UI Capgo yang lebih panjang (kunci induk `appflow_cta_questions`). Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman ionic-appflow.astro. Simpan istilah produk/brand dan developer Capgo secara tepat. Kunci pesan `appflow_cta_questions` (Appflow CTA Pertanyaan). | Teks fragmen HTML dari string UI Capgo yang lebih panjang (kunci induk `capwesome_cta_questions`). Halaman/area: Halaman perbandingan Capawesome. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman capwesome.astro. Simpan istilah produk/brand dan developer Capgo secara tepat. Kunci pesan `capwesome_cta_questions` (Capwesome CTA Pertanyaan). | Teks fragmen HTML dari string UI Capgo yang lebih panjang (kunci induk `consulting_faq_subtitle`). Halaman/area: Halaman layanan konsultasi. Peran: Judul atau tagline bagian. Dilihat di: halaman consulting.astro. Simpan istilah produk/brand dan developer Capgo secara tepat. Kunci pesan `consulting_faq_subtitle` (Judul FAQ Layanan Konsultasi). | Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman ionic-appflow.astro, halaman ionic-enterprise-plugins.astro, halaman solusi/ionic-enterprise-plugins.astro. Kunci pesan `appflow_plugins_or` (Appflow Plugin Atau). app_admin, app_developer, app_uploader, app_readeratau app_preview).

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

Pengaturan otomatis saluran pratinjau

Hubungkan app_preview hanya ke aplikasi pratinjau untuk CI yang membuat saluran pratinjau sementara, tidak publik, mengunggah dan mempromosikan sebuah 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 rekaman aplikasi, bukan identifikasi aplikasi publik yang digunakan oleh perintah CLI (misalnya, com.example.app) Pengikat tetap terikat ke organisasi bahkan ketika kunci tidak memiliki peran organisasi-wide.

Level aplikasi app_preview termasuk hanya app.read, app.read_bundles, app.upload_bundle, dan app.create_channel. Ketika kunci itu membuat sebuah saluran, Capgo secara otomatis menambahkan sebuah channel_preview pautan pada saluran yang baru saja dibuat. Pautan anak itu memberikan channel.read, channel.promote_bundle, dan channel.delete hanya untuk saluran yang kunci itu buat.

app_preview menyimpan app.read, jadi ini bukan isolasi ketat baca saluran: kunci itu mungkin memperlihatkan metadata saluran dalam aplikasi yang dipilih. Pautan anak otomatis membatasi mutasi siklus hidup ke saluran yang kunci itu buat.

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

Gunakan channel delete <preview-channel> <public-app-id> --delete-bundle untuk pembersihan. Ini adalah rute pembersihan pratinjau atomik, yang memeriksa kepemilikan dan menghapus hanya saluran pratinjau dan paket terkait yang dipanggil. app_preview tidak memberikan akses umum bundle.delete.

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

Diagram yang menjelaskan bagaimana RBAC API mengatur izin kunci

Perizinan pembuatan organisasi

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

Karena izin ini terpisah dari ikatan peran org/app biasa karena organisasi baru belum ada ketika __CAPGO_KEEP_0__ dipanggil. Untuk membuat organisasi dengan kunci __CAPGO_KEEP_0__: POST /organization/ Kunci API harus termasuk

The API key must include org.create Kunci __CAPGO_KEEP_0__ yang sama juga harus memiliki izin organisasi-skop yang aktif global_permissions.
The same API key must also have a current organization-scoped org_admin context: Fragment teks HTML dari string Capgo UI yang lebih panjang (kunci induk `alternatives_cta_questions`). Halaman/area: Halaman perbandingan alternatif Capacitor live-update. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman alternatives.astro. Simpan istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `alternatives_cta_questions` (Pertanyaan Tindakan Alternatif). | Fragment teks HTML dari string Capgo UI yang lebih panjang (kunci induk `appflow_cta_questions`). Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman ionic-appflow.astro. Simpan istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `appflow_cta_questions` (Pertanyaan Tindakan Appflow). | Fragment teks HTML dari string Capgo UI yang lebih panjang (kunci induk `capwesome_cta_questions`). Halaman/area: Halaman perbandingan Capawesome. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman capwesome.astro. Simpan istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `capwesome_cta_questions` (Pertanyaan Tindakan Capwesome). | Fragment teks HTML dari string Capgo UI yang lebih panjang (kunci induk `consulting_faq_subtitle`). Halaman/area: Halaman layanan konsultasi. Peran: Judul bagian atau tagline. Dilihat di: halaman consulting.astro. Simpan istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `consulting_faq_subtitle` (Judul Subjudul FAQ Konsultasi). | Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman ionic-appflow.astro, halaman ionic-enterprise-plugins.astro, halaman solusi/ionic-enterprise-plugins.astro. Kunci pesan `appflow_plugins_or` (Appflow Plugins Atau). org_super_admin izin.
Kunci API baru tidak menerima org.create oleh default. Aktifkan Biarkan membuat organisasi saat membuat atau mengedit kunci RBAC API di dashboard.
Existing write-capable org admin/super admin API keys were backfilled with org.create Jadi integrasi yang sudah ada dapat terus membuat organisasi.

Jika kunci API membuat organisasi, Capgo secara otomatis mengasign kunci API yang sama ke org_super_admin pada organisasi yang baru saja dibuat. Hal ini memungkinkan integrasi mengelola organisasi yang baru saja dibuat tanpa perlu mengikat peran secara manual.

Jika Anda membuat kunci API melalui API, termasuk global_permissions bersama dengan pengikat peran 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 Aman (Hashed)

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

Kunci teks biasa Tidak dapat diperoleh setelah pembuatan.
Penghasilan ulang menghasilkan kunci teks biasa baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
Dianjurkan untuk menggunakan kunci yang dihash dalam penggunaan produksi.

Beberapa organisasi mewajibkan kunci yang dihash melalui enforce_hashed_api_keys kebijakan org.

Kadaluarsa

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

Kebijakan organisasi dapat mewajibkan:

Wajib kadaluarsa (require_apikey_expirationSemua kunci baru harus memiliki tanggal kadaluarsa.
Maksimum TTL (max_apikey_expiration_days) — Tanggal kadaluarsa tidak boleh lebih dari N hari ke depan.

Praktik Keamanan Terbaik

Prinsip Privilegi Terendah: Tugaskan peran yang paling terbatas yang masih memungkinkan integrasi Anda berfungsi
Pemutakhiran Reguler: Pemutakhiran kunci API secara berkala menggunakan fitur regenerasi
Penggunaan Penyimpanan yang Aman: Simpan kunci API dengan aman dan jangan pernah memasukkannya ke dalam pengontrol versi
Penggunaan Kunci yang DicocokkanMembuat kunci yang aman (dihash) untuk integrasi produksi
Set Waktu BerlakuMembuat kunci yang digunakan untuk akses sementara atau CI/CD harus selalu memiliki tanggal berlaku
Pengaturan Ruang LingkupMembuat kunci yang hanya dapat digunakan oleh aplikasi tertentu dengan peran yang minimal

Penggunaan Umum

Pengintegrasian CI/CDKunci yang dibuat untuk aplikasi tertentu dengan peran yang minimal app_uploader atau app_developer Membuat kunci yang hanya dapat digunakan oleh aplikasi tertentu dengan peran yang minimal, dan tentukan tanggal berlaku
Peran, dan tentukan tanggal berlaku: Gunakan app_preview di aplikasi preview saja atau aplikasi-aplikasi lainnya ketika CI perlu mengunggah bundle, membuat saluran sementara, dan membersihkan saluran dan bundle sendiri secara atomik.
Pengaturan Deploymen: Gunakan kunci dengan app_developer peran untuk skrip pengaturan deploymen otomatis.
Alat Pemantauan: Buat kunci dengan app_reader peran untuk integrasi pemantauan eksternal.
Akses Administrator: Gunakan kunci dengan org_admin peran dengan hati-hati untuk alat-alat administratif.
Integrasi Pihak KetigaMembuat kunci yang dibatasi pada aplikasi tertentu dengan peran yang diperlukan minimal.
Pengaturan OrganisasiMenggunakan sebuah org_admin atau org_super_admin Bagaimana cara memilih antara alternatif ini? org.create Membuat kunci RBAC dengan hanya untuk otomatisasi yang dipercaya yang perlu membuat organisasi.

Teruskan dari API Kunci

Jika Anda menggunakan __CAPGO_KEEP_0__ Kunci API Keys @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-login-social @capgo/capacitor-social-login untuk detail implementasi di @capgo/capacitor-login-social, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-biometrik-native untuk detail implementasi di @capgo/capacitor-biometrik-native, Autentikasi dua faktor untuk detail implementasi di Autentikasi dua faktor, dan SSO (Perusahaan) untuk detail implementasi di SSO (Perusahaan).