API Kunci

Copy sebuah prompt pengaturan dengan langkah-langkah instalasi dan panduan markdown lengkap untuk plugin ini.

API kunci digunakan untuk mengautentikasi permintaan ke Capgo API. Kunci khusus organisasi dan dapat diberikan peran RBAC untuk kontrol akses 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-key, authorization Jendela terminal

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

__CAPGO_KEEP_2__ juga dapat diterima: Saluran API menerima authorization atau capgkey; gunakan salah satu header untuk otomatisasi saluran pratinjau.

Otorisasi Hak Akses Berdasarkan Peran (RBAC)

API keys menggunakan sistem otorisasi hak 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. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `alternatives_cta_questions` (Alternatives CTA Questions). | HTML teks fragmen 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. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `appflow_cta_questions` (Appflow CTA Questions). | HTML teks fragmen 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. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `capwesome_cta_questions` (Capwesome CTA Questions). | HTML teks fragmen 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. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `consulting_faq_subtitle` (Consulting FAQ Subtitle). | 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 Or). Peran Aplikasi 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 umum, 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 organisasi bahkan ketika kunci tidak memiliki peran organisasi luas.

Aplikasi-level 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 dibuat oleh kunci itu.

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

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

Pilih channel delete <preview-channel> <public-app-id> --delete-bundle untuk membersihkan. Ini adalah rute membersihkan 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 Pilih kunci App Preview untuk alur kerja pratinjau.

Diagram yang menjelaskan bagaimana RBAC API izin kunci berfungsi

Peran pembuatan organisasi

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

Izin ini terpisah dari ikatan peran organisasi/app biasa karena organisasi baru belum ada ketika POST /organization/ di panggil. Untuk membuat organisasi dengan kunci API:

Kunci API harus termasuk org.create dalam global_permissions.
Sama kunci API juga harus memiliki organisasi-skop saat ini org_admin atau org_super_admin context: Fragment teks HTML dari string Capgo UI yang lebih panjang (kunci induk `alternatives_cta_questions`). Halaman/area: Halaman perbandingan Capacitor live-update. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman alternatives.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. Kunci pesan `alternatives_cta_questions` (Alternatives CTA Questions). | Fragment teks HTML dari string Capgo UI yang lebih panjang (kunci induk `appflow_cta_questions`). Halaman/area: Halaman perbandingan/migrasi Appflow. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman ionic-appflow.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. Kunci pesan `appflow_cta_questions` (Appflow CTA Questions). | 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 Capgo produk/merek dan istilah pengembang secara tepat. Kunci pesan `capwesome_cta_questions` (Capwesome CTA Questions). | Fragment teks HTML dari string Capgo UI yang lebih panjang (kunci induk `consulting_faq_subtitle`). Halaman/area: Halaman layanan konsultasi. Peran: Judul atau tagline bagian. Dilihat di: halaman consulting.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. Kunci pesan `consulting_faq_subtitle` (Consulting FAQ Subtitle). | Halaman/area: Halaman perbandingan/migrasi 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 Or).
New API keys do not receive org.create Organisasi baru __CAPGO_KEEP_0__ tidak menerima oleh default. Aktifkan saat membuat atau mengedit kunci RBAC API di dashboard.
Kunci admin/super admin organisasi yang dapat menulis sudah diisi ulang dengan API org.create Jadi integrasi yang sudah ada masih bisa membuat organisasi.

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

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 (Ditulis Hash)

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

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 produksi.

Beberapa organisasi mengenakan 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 mengenakan:

Wajib kadaluarsa (require_apikey_expiration) — Semua kunci baru harus memiliki batas waktu.
Maksimum TTL (max_apikey_expiration_days) — Batas waktu tidak boleh lebih dari N hari ke depan.

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 Anda dengan aman dan jangan pernah mengkomitnya ke kontrol versi
Gunakan Kunci TerenkripsiMembuat kunci yang aman (dihash) untuk integrasi produksi
Set Waktu BerlakuMembuat kunci yang selalu memiliki tanggal berlaku untuk akses sementara atau CI/CD
Penggunaan Ruang LingkupMembuat kunci yang terbatas pada aplikasi tertentu dengan peran yang minimal

Penggunaan Umum

Pengintegrasian CI/CDPage/area: Capgo Builder / produk native cloud build. Role: Label atau item navigasi pendek. Message key `native_build_feature_ci_cd` (Fitur Pembangunan Asli Ci Cd). app_uploader Membuat kunci yang terbatas pada aplikasi tertentu dengan app_developer atau
Page/area: Halaman perbandingan alternatif Capacitor. Role: Paragraf pemasaran atau hukum yang panjang. Seen in: page alternatives.astro. Preserve Capgo product/brand dan developer terms exactly. Message key `alternatives_cta_questions` (Pertanyaan Tindakan Alternatif). | Page/area: Halaman perbandingan Appflow. Role: Paragraf pemasaran atau hukum yang panjang. Seen in: page ionic-appflow.astro. Preserve Capgo product/brand dan developer terms exactly. Message key `appflow_cta_questions` (Pertanyaan Tindakan Appflow). | Page/area: Halaman perbandingan Capawesome. Role: Paragraf pemasaran atau hukum yang panjang. Seen in: page capwesome.astro. Preserve Capgo product/brand dan developer terms exactly. Message key `capwesome_cta_questions` (Pertanyaan Tindakan Capwesome). | Page/area: Halaman layanan konsultasi. Role: Judul atau tagline bagian. Seen in: page consulting.astro. Preserve Capgo product/brand dan developer terms exactly. Message key `consulting_faq_subtitle` (Judul Subjudul FAQ Konsultasi). | Page/area: Halaman perbandingan Appflow. Role: Label atau item navigasi pendek. Seen in: page ionic-appflow.astro, page ionic-enterprise-plugins.astro, page solutions/ionic-enterprise-plugins.astro. Message key `appflow_plugins_or` (Appflow Plugins Atau).: Gunakan app_preview pada aplikasi preview atau aplikasi-apliksi hanya 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 untuk aplikasi tertentu dengan peran yang diperlukan minimal.
Pengaturan OrganisasiMenggunakan org_admin atau org_super_admin Bagaimana cara membuat aplikasi yang lebih baik? Apakah Anda ingin meningkatkan produktivitas tim Anda? Apakah Anda ingin meningkatkan keamanan aplikasi Anda? Apakah Anda ingin meningkatkan pengalaman pengguna Anda? Apakah Anda ingin meningkatkan kemampuan analisis Anda? Apakah Anda ingin meningkatkan kemampuan integrasi Anda? Apakah Anda ingin meningkatkan kemampuan keamanan Anda? Apakah Anda ingin meningkatkan kemampuan pengembangan Anda? Apakah Anda ingin meningkatkan kemampuan pengujian Anda? Apakah Anda ingin meningkatkan kemampuan analisis Anda? Apakah Anda ingin meningkatkan kemampuan integrasi Anda? 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 untuk merencanakan autentikasi dan aliran akun, hubungkannya dengan @API/__CAPGO_KEEP_1__-social-login Membuat kunci yang dibatasi untuk aplikasi tertentu dengan peran yang diperlukan minimal. @capgo/capacitor-social-login untuk detail implementasi di @capgo/capacitor-social-login, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-native-biometric untuk detail implementasi di @capgo/capacitor-native-biometric, Pengaman Dua Faktor untuk detail implementasi di Pengaman Dua Faktor, dan SSO (Perusahaan) untuk detail implementasi di SSO (Perusahaan).