Kunci API

Kunci API digunakan untuk autentikasi request ke API Capgo. Kunci ini bersifat spesifik per organisasi dan dapat diberikan role RBAC untuk kontrol akses yang lebih mendalam. Setiap kunci juga dapat memiliki tanggal kedaluwarsa opsional dan dapat dibuat sebagai kunci “secure” (hashed) di mana nilai plain-text hanya akan ditampilkan satu kali.

Menggunakan kunci API

Gunakan authentication header yang didokumentasikan oleh endpoint. Untuk request dengan API-key, authorization diterima:

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

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

RBAC Permissions

Kunci API menggunakan sistem role-based access control (RBAC) yang sama dengan akun pengguna. Saat membuat atau mengelola kunci melalui web app atau API, Anda menetapkan role pada dua level:

• Role Organisasi — Menentukan izin dasar kunci di seluruh organisasi (misalnya, org_admin atau org_member).
• Peran aplikasi — Izin per-app (misalnya, app_admin, app_developer, app_uploader, app_reader, atau app_preview).

Jika kunci API memiliki role binding eksplisit, hanya binding tersebut yang dievaluasi untuk pengecekan 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 tempat key tersebut dibuat.

app_preview tetap app.read, jadi ini bukan isolasi channel-read yang ketat: key tersebut dapat melihat metadata channel di app yang dipilih. Pembatasan automatic child binding mutasi lifecycle pada channel tempat key tersebut dibuat.

Capgo mencatat App Preview key yang mengunggah setiap bundle. Key tersebut hanya dapat mempromosikan bundle miliknya sendiri ke setiap preview channel yang dibuatnya. Key ini tidak memiliki akses lifecycle channel ke channel default/utama yang sudah ada, channel yang dibuat oleh preview key lain, atau bundle milik key 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 preview yang bersifat atomik dan telah diperiksa kepemilikannya; rute ini hanya menghapus channel preview dan bundle terkait milik key yang memanggil. app_preview tidak memberikan akses generik bundle.delete.

Untuk setup dashboard dan contoh lengkap CLI, lihat Gunakan App Preview key untuk workflow preview.

Catatan

Key tanpa role binding akan beralih ke sistem berbasis mode lama (read, upload, write, all). Mode ini sudah deprecated — gunakan role RBAC sebagai gantinya.

Izin pembuatan organisasi

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

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

• Key API harus menyertakan org.create di global_permissions.
• Kunci API yang sama juga harus memiliki cakupan organisasi yang aktif org_admin atau org_super_admin binding.
• Key API baru tidak akan menerima org.create secara default. Aktifkan Izinkan membuat organisasi saat membuat atau mengedit key API RBAC di dashboard.
• Key API admin/super admin organisasi yang memiliki akses write sudah di-backfill dengan org.create agar integrasi yang ada tetap bisa membuat organisasi.

Saat key API membuat organisasi, Capgo secara otomatis menetapkan key API yang sama sebagai org_super_admin pada organisasi yang baru dibuat. Ini memungkinkan integrasi mengelola organisasi yang baru dibuat tanpa perlu manual role binding terpisah.

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

Key Aman (Hashed)

Saat membuat secure key, server men-generate material kunci dan mengembalikan nilai plain-text satu kali saja. Hanya hash yang disimpan. Ini berarti:

• Kunci plain-text tidak dapat diambil kembali setelah dibuat.
• Regenerasi akan menghasilkan kunci plain-text baru (hanya muncul sekali) dan memperbarui hash yang tersimpan.
• Hashed keys sangat direkomendasikan untuk penggunaan production.

Beberapa organisasi mewajibkan penggunaan hashed key melalui enforce_hashed_api_keys org policy.

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 Least Privilege: Berikan role paling terbatas yang tetap memungkinkan integrasi Anda berjalan
2. Rotasi Berkala: Rotasi key API Anda secara periodik menggunakan fitur regenerate
3. Penyimpanan Aman: Simpan key API dengan aman dan jangan pernah commit ke version control
4. Gunakan Hashed Keys: Buat key yang aman (hashed) untuk integrasi produksi
5. Atur Masa Berlaku: Selalu atur tanggal kedaluwarsa pada key yang digunakan untuk akses sementara atau CI/CD
6. Batasan Scope: Batasi key hanya untuk aplikasi tertentu dengan role minimum yang diperlukan

Kasus Penggunaan Umum

1. Integrasi CI/CD: Buat key dengan scope aplikasi tertentu menggunakan app_uploader atau app_developer role, dan atur tanggal kedaluwarsanya.
2. Channel Preview PR: Gunakan app_preview hanya pada aplikasi preview saat CI perlu upload bundle, membuat channel sementara, dan membersihkan channel serta bundle miliknya secara atomik.
3. Otomatisasi deployment: Gunakan key dengan app_developer role untuk script deployment otomatis.
4. Alat Monitoring: Buat key dengan app_reader role untuk integrasi monitoring eksternal.
5. Akses Admin: Gunakan key dengan org_admin role secara bijak untuk tools administratif.
6. Integrasi Pihak Ketiga: Buat key yang dibatasi ke app tertentu dengan role minimum.
7. Penyediaan Organisasi: Gunakan org_admin atau org_super_admin key RBAC dengan org.create hanya untuk otomatisasi terpercaya 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).