API Kunci

API keys are used to authenticate requests to the Capgo API. Keys are organization-specific and can be assigned RBAC roles for fine-grained access control. Each key can also have an optional expiration date and can be created as a “secure” (hashed) key where the plain-text value is only shown once.

Menggunakan kunci API

Masukkan kunci API Anda ke dalam x-api-key bagian kepala setiap permintaan:

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

Kepala juga dapat diterima tetapi lebih ditujukan untuk token JWT. Ketika nilai adalah kunci __CAPGO_KEEP_0__ yang berformat UUID, maka berfungsi, tetapi authorization header is also accepted but is primarily intended for JWT tokens. When the value is a UUID-formatted API key it works, but x-api-key Izin Akses Berdasarkan Peran (RBAC)

Judul bagian “Izin Akses Berdasarkan Peran (RBAC)”

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app, you assign roles at two levels:

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

Jika kunci API memiliki pengikat peran eksplisit, hanya pengikat-pengikat tersebut dipertimbangkan untuk verifikasi izin. Izin pribadi pemilik kunci tidak diwarisi oleh kunci.

Pertanyaan

Kunci tanpa pengikat peran kembali ke sistem berbasis mode (read, upload, write, all). Mode-mode ini sudah usang — gunakan peran RBAC sebaliknya.

Pembuatan izin organisasi

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

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

• Kunci API harus termasuk org.create dalam global_permissions.
• Sama kunci API juga harus memiliki ikatan organisasi-scope org_admin atau org_super_admin terikat.
• Kunci API baru tidak menerima org.create oleh default. Aktifkan Mengizinkan pembuatan organisasi ketika membuat atau mengedit kunci RBAC API di dashboard.
• Existing write-capable org admin/super admin API keys were backfilled with org.create agar integrasi yang ada dapat terus membuat organisasi.

Ketika kunci API membuat organisasi, Capgo secara otomatis mengasign kunci API yang sama org_super_admin pada 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, 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 (Hashed) yang Aman

When membuat kunci yang 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.
• Pengulangan menghasilkan kunci teks biasa baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Rekomendasi kunci hash untuk penggunaan produksi.

Beberapa organisasi mengenakan kunci hash melalui enforce_hashed_api_keys kebijakan org.

Batas Waktu

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

Kebijakan organisasi dapat mengenakan:

• Wajib Kadaluarsa (require_apikey_expiration) — Semua kunci baru harus memiliki kadaluarsa.
• Maksimum TTL (max_apikey_expiration_days) — 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 regenerate
3. Penyimpanan Aman: Simpan kunci API secara aman dan tidak pernah komit ke pengawasan versi
4. Gunakan Kunci Hash: Buat kunci hash yang aman untuk integrasi produksi
5. Atur Kadaluarsa: Selalu atur tanggal kadaluarsa pada kunci yang digunakan untuk akses sementara atau akses CI/CD
6. Pengaturan Batasan Ruang: Batasi kunci pada aplikasi tertentu dengan peran yang diperlukan minimal

Penggunaan Umum

1. Pengintegrasian CI/CD: Buat kunci yang dipasang pada aplikasi tertentu dengan app_uploader atau app_developer peran, dan atur tanggal kadaluarsa
2. Automasi Pengaturan: Gunakan kunci dengan app_developer peran untuk skrip pengaturan otomatis
3. Alat Pemantauan: Buat kunci dengan app_reader peran untuk integrasi pemantauan eksternal
4. Akses Administrator: Gunakan kunci dengan org_admin peran dengan hati-hati untuk alat administratif
5. Integrasi Pihak Ketiga: Buat kunci yang terbatas pada aplikasi tertentu dengan peran yang diperlukan minimal
6. Penyediaan Organisasi: Gunakan RBAC key dengan org_admin atau org_super_admin RBAC key dengan hanya untuk otomatisasi yang dipercaya yang perlu membuat organisasi org.create Teruskan dari __CAPGO_KEEP_0__ Keys

Judul bagian “Teruskan dari API Keys”

__CAPGO_KEEP_0__ Keys API Keys @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login untuk detail implementasi di @capgo/capacitor-social-login, @capgo/capacitor-passkey @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).