Kunci API

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

Menggunakan kunci API

Gunakan header autentikasi yang didokumentasikan oleh endpoint. Untuk permintaan kunci API, authorization diterima:

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

Beberapa endpoint juga menerima header kunci khusus. Yang Channel API menerima authorization atau capgkey; gunakan salah satu header tersebut untuk otomasi preview-channel.

RBAC Permissions

Kunci API menggunakan sistem kontrol akses berbasis peran (RBAC) yang sama dengan akun pengguna. Saat membuat atau mengelola kunci melalui web app 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 per aplikasi (misalnya, app_admin, app_developer, app_uploader, app_reader, atau app_preview).

Jika kunci API memiliki pengikatan peran eksplisit, hanya pengikatan tersebut dievaluasi untuk pemeriksaan izin. Izin pribadi pemilik kunci tidak diwariskan ke kunci tersebut.

Pratinjau otomatisasi channel

Ikatkan app_preview hanya ke preview app untuk CI yang membuat preview channel sementara dan non-publik, meng-upload dan mempromosikan bundle, lalu 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 pemilik app tersebut. app_id adalah UUID internal dari record app, bukan identifier app publik yang digunakan oleh perintah CLI (misalnya, com.example.app). Binding ini tetap terikat pada organisasi meskipun key tersebut tidak memiliki role di seluruh organisasi.

Role tingkat app app_preview hanya mencakup app.read, app.read_bundles, app.upload_bundle, dan app.create_channel. Saat key tersebut membuat channel, Capgo secara otomatis menambahkan channel_preview binding pada channel yang baru dibuat. Child binding tersebut memberikan channel.read, channel.promote_bundle, dan channel.delete hanya untuk channel yang dibuat key tersebut.

app_preview mempertahankan app.read, jadi ini bukan isolasi baca channel yang ketat: key dapat mengenumerasi metadata channel di app yang dipilih. Binding child otomatis membatasi mutasi lifecycle ke channel yang dibuat key tersebut.

Capgo mencatat App Preview key yang mengunggah setiap bundle. Key hanya dapat mempromosikan bundle miliknya sendiri ke setiap preview channel yang dibuatnya. Tidak ada akses lifecycle channel ke channel default/main yang sudah ada, channel yang dibuat oleh preview key lain, atau bundle milik key lain. Untuk workflow ini, hilangkan public dan jangan pernah gunakan --default.

Gunakan channel delete <preview-channel> <public-app-id> --delete-bundle untuk pembersihan. Ini adalah route pembersihan preview yang atomik dan memeriksa kepemilikan; hanya menghapus preview channel dan bundle tertaut milik key pemanggil. app_preview tidak memberikan akses generik bundle.delete.

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

Catatan

Kunci tanpa pengikatan peran akan kembali ke sistem berbasis mode lama (read, upload, write, all). Mode ini sudah tidak didukung — gunakan peran RBAC sebagai gantinya.

Izin pembuatan organisasi

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

Izin ini terpisah dari binding peran org/app biasa karena organisasi baru belum ada saat POST /organization/ dipanggil. Untuk membuat organisasi dengan key API:

• Key API harus mencakup org.create di global_permissions.
• Kunci API yang sama juga harus memiliki scope organisasi yang aktif org_admin atau org_super_admin binding.
• Key API baru tidak mendapatkan org.create secara default. Aktifkan Izinkan membuat organisasi saat membuat atau mengedit key API RBAC di dashboard.
• Key API admin org/super admin yang sudah ada dan punya akses tulis telah di-backfill dengan org.create sehingga integrasi yang sudah ada dapat terus membuat organisasi.

Saat sebuah kunci API membuat organisasi, Capgo secara otomatis menetapkan kunci API yang sama sebagai org_super_admin pada organisasi yang baru dibuat. Ini memungkinkan integrasi mengelola organisasi yang baru saja dibuat tanpa perlu pengikatan peran manual terpisah.

Jika Anda membuat kunci API melalui API, sertakan global_permissions bersama dengan pengikatan 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 pembuatan organisasi. Penghapusan organisasi tetap memerlukan izin hapus pada organisasi target, biasanya melalui org_super_admin.

Key Aman (Hashed)

Saat membuat kunci aman, server menghasilkan materi kunci dan mengembalikan nilai plain-text sekali. Hanya hash yang disimpan. Ini berarti:

• Kunci plain-text tidak dapat diambil kembali setelah pembuatan.
• Regenerasi menghasilkan kunci teks biasa baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Kunci ber-hash direkomendasikan untuk penggunaan produksi.

Beberapa organisasi mewajibkan penggunaan hashed key melalui enforce_hashed_api_keys kebijakan org.

Masa berlaku

Key dapat memiliki tanggal kedaluwarsa opsional. Key yang sudah kedaluwarsa akan ditolak di layer pemeriksaan permission.

Kebijakan organisasi dapat mewajibkan:

• Kedaluwarsa wajib (require_apikey_expiration) — Semua key baru wajib memiliki masa berlaku.
• TTL maksimum (max_apikey_expiration_days) — Masa berlaku tidak boleh lebih dari N hari dari sekarang.

Praktik Terbaik Keamanan

1. Prinsip Hak Akses Minimal: Berikan peran paling restriktif yang masih memungkinkan integrasi Anda berfungsi
2. Rotasi Berkala: Rotasi kunci API Anda secara berkala menggunakan fitur regenerate
3. Penyimpanan Aman: Simpan kunci API dengan aman dan jangan pernah commit ke version control
4. Gunakan Kunci Hashed: Buat kunci aman (hashed) untuk integrasi produksi
5. Atur Kedaluwarsa: Selalu atur tanggal kedaluwarsa untuk kunci yang digunakan untuk akses sementara atau CI/CD
6. Pembatasan Scope: Batasi key ke aplikasi tertentu dengan role minimum yang diperlukan

Kasus Penggunaan Umum

1. Integrasi CI/CD: Buat key yang dibatasi ke aplikasi tertentu dengan app_uploader atau app_developer role, dan atur tanggal kedaluwarsa.
2. Channel Preview PR: Gunakan app_preview hanya pada aplikasi preview atau beberapa aplikasi preview saat CI perlu mengunggah bundle, membuat channel sementara, dan membersihkan channel serta bundle-nya sendiri secara atomik.
3. Otomatisasi deployment: Gunakan kunci dengan app_developer role untuk skrip deployment otomatis.
4. Tool Monitoring: Buat kunci dengan app_reader role untuk integrasi monitoring eksternal.
5. Akses Admin: Gunakan kunci dengan org_admin role secara terbatas untuk alat administrasi.
6. Integrasi Pihak Ketiga: Buat kunci yang dibatasi untuk aplikasi tertentu dengan role minimum yang diperlukan.
7. Provisioning Organisasi: Gunakan org_admin atau org_super_admin Kunci RBAC dengan org.create hanya untuk otomasi tepercaya yang perlu membuat organisasi.

Lanjutkan dari API Keys

Jika Anda menggunakan Kunci API untuk merencanakan alur autentikasi dan akun, hubungkan dengan @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 pada Two-factor authentication, dan SSO (Enterprise) untuk detail implementasi pada SSO (Enterprise).