API Kunci

API kunci digunakan untuk mengautentikasi permintaan ke Capgo API. Kunci-kunci ini spesifik organisasi dan dapat diberikan peran RBAC untuk kontrol akses yang lebih halus. Setiap kunci juga dapat memiliki tanggal kadaluarsa yang opsional dan dapat dibuat sebagai “aman” (dihash) di mana nilai teks biasa hanya ditampilkan sekali.

Menggunakan kunci API

Pasang kunci API Anda di x-api-key bagian kepala setiap permintaan:

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

Kepala paling tidak juga diterima tetapi sebenarnya dimaksudkan untuk token JWT. Ketika nilai adalah sebuah UUID yang di-format __CAPGO_KEEP_0__ kunci, itu 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 RBAC

Bagian berjudul “Izin 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:

• — Menetapkan izin dasar kunci di seluruh organisasi (misalnya Peran Aplikasi org_admin, org_member).
• — Izin opsional per-aplikasi (misalnya Jika sebuah kunci __CAPGO_KEEP_0__ memiliki pengikat peran eksplisit, app_admin, app_developer, app_uploader, app_reader).

If an API key has explicit role bindings, Izin RBAC Permissions dievaluasi untuk periksaan izin. Izin pribadi pemilik kunci tidak diwariskan oleh kunci.

Pesan

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

Izin Pembuatan Organisasi

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

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

• Kunci API harus termasuk org.create di global_permissions.
• Kunci API yang sama harus juga memiliki organisasi yang berlaku saat ini. org_admin atau org_super_admin pengikat.
• Kunci API baru tidak menerima org.create oleh default. Aktifkan Izinkan membuat organisasi saat membuat atau mengedit kunci RBAC API di dashboard.
• Existing write-capable org admin/super admin API keys were backfilled with org.create sehingga integrasi yang ada dapat terus membuat organisasi.

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

Jika Anda membuat kunci API melalui API, pastikan global_permissions bersama dengan pengikat 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

Saat membuat kunci aman, server menghasilkan bahan kunci dan mengembalikan nilai teks biasa sekali. Hanya hash yang disimpan. Ini berarti:

• Kunci teks biasa tidak dapat diretrive setelah pembuatan.
• Regenerasi menghasilkan kunci teks biasa baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Kunci hash disarankan untuk penggunaan produksi.

Beberapa organisasi mengenakan kunci yang di-hash melalui kebijakan org. enforce_hashed_api_keys __CAPGO_KEEP_0__

Masa Berlaku

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

Kebijakan organisasi dapat mengenakan:

• Masa Berlaku Wajib (require_apikey_expiration) — Semua kunci baru harus memiliki masa berlaku.
• Masa Aktif Maksimum (max_apikey_expiration_days) — Masa berlaku 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. Rotasi Teratur: Rotasi kunci API secara berkala menggunakan fitur regenerasi
3. Penyimpanan yang Aman: Simpan kunci API secara aman dan tidak pernah komit ke pengendalian versi
4. Pakai Kunci Hashed: Buat kunci yang aman (dihash) untuk integrasi produksi
5. Atur Kadaluarsa: Selalu atur tanggal kadaluarsa pada kunci yang digunakan untuk akses sementara atau akses CI/CD
6. Pengaturan Batasan: Batasi kunci ke aplikasi tertentu dengan peran yang paling sedikit yang diperlukan

Kasus Penggunaan Umum

1. Integrasi CI/CD: Buat kunci yang terkait dengan aplikasi tertentu dengan app_uploader atau app_developer peran, dan tetapkan tanggal kedaluwarsa
2. Automasi Pengembangan: Gunakan kunci dengan app_developer peran untuk skrip otomatisasi pengembangan
3. Alat Pemantauan: Buat kunci dengan app_reader peran untuk integrasi pemantauan eksternal
4. Akses Admin: 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 minimal
6. Penyediaan Organisasi: Gunakan kunci org_admin atau org_super_admin RBAC kunci dengan org.create hanya untuk otomatisasi yang dipercaya yang memerlukan pembuatan organisasi

Teruskan dari API Kunci

Jika Anda menggunakan API Kunci untuk merencanakan autentikasi dan alur 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-biometrik-nativ untuk detail implementasi di @capgo/capacitor-biometrik-nativ, Autentikasi Dua Faktor untuk detail implementasi di Autentikasi Dua Faktor, dan SSO (Enterprise) untuk detail implementasi di SSO (Enterprise).