API Keys

API kunci digunakan untuk menerapkan 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 Terminal jendela

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

__CAPGO_KEEP_0__-key Saluran-saluran API menerima authorization atau capgkeyguna salah satu header untuk otomatisasi saluran pratinjau.

Izin Akses Berdasarkan Peran (RBAC)

API keys 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 — Menentukan izin dasar kunci di seluruh organisasi (misalnya, org_admin atau org_member).
• Peran Aplikasi — Izin aplikasi (misalnya, 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 ke 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 channel, Capgo secara otomatis menambahkan sebuah channel_preview pautan pada channel yang baru saja dibuat. Pautan anak itu memberikan channel.read, channel.promote_bundle, dan channel.delete hanya untuk channel yang dibuat oleh kunci itu.

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

Capgo 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, sebuah channel yang dibuat oleh kunci preview lain, atau bundle milik 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 rute membersihkan pratinjau atomik, yang memeriksa kepemilikan dan hanya menghapus kanal pratinjau dan paket terkait yang dipanggil. app_preview tidak memberikan hak istimewa bundle.delete.

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

Penting

Kunci yang tidak memiliki pengikat peran akan kembali ke sistem berbasis mode yang lama (read, upload, write, allMode-mode ini sudah tidak digunakan lagi — gunakan peran RBAC saja.

Izin pembuatan organisasi

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

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

• Kunci API harus termasuk org.create dalam global_permissions.
• Kunci API yang sama juga harus memiliki organisasi-skop saat ini org_admin atau org_super_admin Kunci __CAPGO_KEEP_0__ harus memiliki izin organisasi-skop saat ini
• untuk membuat organisasi dengan kunci API: org.create izin ini harus diaktifkan izin ini harus diaktifkan 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 mengasosiasikan kunci API yang sama ke organisasi baru tersebut. org_super_admin Hal ini memungkinkan integrasi mengelola organisasi yang baru saja dibuat tanpa perlu mengikat peran secara manual.

Jika Anda membuat kunci API melalui API, pastikan untuk mengasosiasikan kunci tersebut dengan peran admin organisasi: global_permissions Salin ke clipboard

{
  "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 Kunci Aman (Hashed) org_super_admin.

Judul bagian “Kunci Aman (Hashed)”

Kunci aman hanya dapat dibuat sekali dan tidak dapat diubah.

• Kunci teks biasa tidak dapat diperoleh setelah pembuatan.
• Regenerasi menghasilkan kunci teks biasa baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Dianjurkan untuk menggunakan kunci yang dihash dalam produksi.

Beberapa organisasi mewajibkan kunci yang dihash melalui enforce_hashed_api_keys org policy.

Kadaluarsa

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

Kebijakan organisasi dapat mewajibkan:

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

Praktik Keamanan Terbaik

1. Prinsip Privasi Terbatas: Tugaskan peran yang paling mengikat yang masih memungkinkan integrasi Anda berfungsi
2. Penggantian Rutin: Ganti kunci API secara berkala menggunakan fitur regenerasi
3. Penyimpanan Aman: Simpan kunci API dengan aman dan tidak pernah komit ke kontrol versi
4. Gunakan Kunci TerenkripsiMembuat kunci aman (dihash) untuk integrasi produksi
5. Set Tanggal KadaluarsaMembuat kunci dengan tanggal kadaluarsa untuk akses sementara atau CI/CD
6. Penggunaan Ruang LingkupMembuat kunci yang terbatas pada aplikasi tertentu dengan peran yang diperlukan minimal

Penggunaan Umum

1. Pengintegrasian CI/CDKunci yang dibuat untuk aplikasi tertentu dengan peran yang diperlukan minimal app_uploader atau app_developer Membuat kunci yang terbatas pada aplikasi tertentu dengan peran yang diperlukan minimal, dan set tanggal kadaluarsa.
2. Saluran Pratinjau PR: Gunakan app_preview hanya pada aplikasi preview atau aplikasi-aplikasi lain ketika CI perlu mengunggah bundle, membuat saluran sementara, dan membersihkan saluran dan bundle sendiri secara atomik.
3. Automasi Pengembangan: Gunakan kunci dengan app_developer peran untuk skrip otomatisasi pengembangan.
4. Alat Pemantauan: Buat kunci dengan app_reader peran untuk integrasi pemantauan eksternal.
5. Akses Administrator: Gunakan kunci dengan org_admin peran dengan hati-hati untuk alat-alat administratif.
6. Integrasi Pihak KetigaBuatlah kunci yang dibatasi untuk aplikasi tertentu dengan peran yang minimal diperlukan.
7. Penyediaan OrganisasiGunakan sebuah org_admin atau org_super_admin Bagaimana cara memilih alternatif terbaik untuk memperbarui aplikasi Anda secara langsung? org.create Gunakan sebuah

Keep going from API Keys

Bagaimana cara memilih alternatif terbaik untuk memperbarui aplikasi Anda secara langsung? API Keys Bagaimana cara memilih alternatif terbaik untuk memperbarui aplikasi Anda secara langsung? @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, Autentikasi dua faktor untuk detail implementasi di Autentikasi dua faktor, dan SSO (Enterprise) untuk detail implementasi di SSO (Enterprise).