API Kunci

API digunakan untuk mengautentikasi permintaan ke Capgo API. Kunci-kunci ini spesifik 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

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. Channel __CAPGO_KEEP_0__ API Menerima authorization atau capgkey; gunakan salah satu header untuk otomatisasi saluran pratinjau.

Izin Akses Berdasarkan Peran (RBAC)

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 – 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_reader, atau app_preview).

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

Automasi saluran pratinjau

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

Pengaturan aplikasi app_preview Fungsi ini hanya mencakup app.read, app.read_bundles, app.upload_bundle, dan app.create_channel. Ketika kunci membuat sebuah saluran, Capgo secara otomatis menambahkan sebuah channel_preview pada saluran baru tersebut. Binding anak tersebut hanya memberikan channel.read, channel.promote_bundle, dan channel.delete untuk saluran yang dibuat oleh kunci tersebut.

app_preview Menyimpan app.read, sehingga ini bukan isolasi ketat membaca saluran: kunci tersebut mungkin dapat memperoleh metadata saluran dalam aplikasi yang dipilih. Binding anak otomatis membatasi mutasi siklus hidup ke saluran yang dibuat oleh kunci tersebut.

Capgo merekam kunci App Preview yang mengunggah setiap bundle. Kunci tersebut hanya dapat mempromosikan bundle sendiri ke setiap saluran preview yang dibuatnya. Kunci tersebut tidak memiliki akses siklus hidup saluran untuk saluran default/main yang sudah ada, sebuah saluran yang dibuat oleh kunci preview lain, atau bundle milik kunci lain. Untuk alur kerja ini, abaikan public dan jangan pernah gunakan --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 kunci yang memanggil. app_preview tidak memberikan hak generic bundle.delete.

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

Peringatan

Kunci tanpa pengikatan peran akan kembali ke sistem berbasis mode (read, upload, write, all). Mode-mode ini sudah tidak digunakan lagi — gunakan peran RBAC.

Izin Pembuatan Organisasi

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

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

• Kunci API harus termasuk org.create dalam global_permissions.
• Kunci API yang sama juga harus memiliki ikatan organisasi-scope org_admin atau org_super_admin yang aktif.
• Kunci API baru tidak menerima org.create oleh default. Aktifkan Izinkan membuat organisasi ketika membuat atau mengedit kunci RBAC API di dashboard.
• Admin/super admin yang sudah ada untuk organisasi yang dapat ditulis kembali memiliki kunci API yang diisi ulang dengan org.create agar integrasi yang sudah ada dapat terus membuat organisasi.

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

Jika Anda membuat kunci API melalui API, pastikan global_permissions termasuk dalam pengaturan 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 (Dikunci Hash)

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.
• Penghasil ulang menghasilkan kunci teks sederhana baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Kunci yang dihash direkomendasikan untuk penggunaan produksi.

Beberapa organisasi menerapkan kunci dihash melalui enforce_hashed_api_keys kebijakan org.

Masa Berlaku

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

Kebijakan organisasi dapat menerapkan:

• Masa Berlaku Wajib (require_apikey_expiration) — Semua kunci baru harus memiliki tenggat waktu.
• Maksimum TTL (max_apikey_expiration_days) — Masa kadaluarsa tidak dapat 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 Teratur: Ganti kunci API secara berkala menggunakan fitur regenerasi
3. Pengamanan Penyimpanan: Simpan kunci API secara aman dan tidak pernah komit ke pengendalian versi
4. Penggunaan Kunci Hashed: Buat kunci yang aman (dihash) untuk integrasi produksi
5. Set Expirasi: Selalu tetapkan tanggal kedaluwarsa pada kunci yang digunakan untuk akses sementara atau akses CI/CD
6. Pengaturan Ruang: Batasi kunci pada aplikasi tertentu dengan peran yang minimal

Penggunaan Umum

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

Lanjutkan dari API Kunci

Jika Anda menggunakan API Kunci untuk merencanakan aliran autentikasi dan akun, hubungkannya dengan @capgo/capacitor-login-social untuk detail implementasi di @capgo/capacitor-login-social, @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 (Perusahaan) untuk detail implementasi di SSO (Perusahaan).