Kunci API

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

Menggunakan kunci API

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

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

Bagian kepala juga diterima tetapi lebih ditujukan untuk token JWT. Ketika nilai adalah kunci UUID-berformat __CAPGO_KEEP_0__ 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”']}

Kunci API menggunakan sistem kontrol akses berdasarkan peran (RBAC) yang sama seperti akun pengguna. Ketika membuat atau mengelola kunci melalui aplikasi web, Anda menetapkan peran pada dua tingkat:

• Peran Organisasi — Menetapkan 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 tersebut dipertimbangkan untuk verifikasi izin. Izin pribadi pemilik kunci tidak diwariskan ke kunci.

Catatan

Kunci tanpa pengikat peran kembali ke sistem mode berbasis legasi (read, upload, write, allPenggunaan mode ini telah dihapus — gunakan peran RBAC sebaliknya.

Izin Pembuatan Organisasi

Pembuatan 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/ digunakan. Untuk membuat organisasi dengan kunci API:

• Kunci API harus termasuk org.create di global_permissions.
• Sama kunci API juga harus memiliki ikatan organisasi-scope org_admin atau org_super_admin binding.
• Kunci API baru tidak menerima org.create dengan 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 agar integrasi yang sudah ada dapat terus membuat organisasi.

Saat kunci API membuat organisasi, Capgo secara otomatis mengasign kunci API yang sama pada org_super_admin di organisasi yang baru dibuat. Hal ini memungkinkan integrasi mengelola organisasi yang baru saja dibuat tanpa perlu pengikat 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

Saat 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.
• Regenerasi menghasilkan kunci teks biasa baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Kunci hash disarankan untuk penggunaan produksi.

Beberapa organisasi mewajibkan kunci hash melalui enforce_hashed_api_keys kebijakan org.

Kadaluarsa

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

Kebijakan organisasi dapat menegaskan:

• Wajib kadaluarsa (require_apikey_expiration) — Semua kunci baru harus memiliki kadaluarsa.
• Jangka waktu maksimum (max_apikey_expiration_days) — Kadaluarsa tidak dapat lebih jauh dari N hari dari sekarang.

Praktik Keamanan Terbaik

1. Prinsip Privilegi Terendah: Tugaskan peran yang paling restriktif yang masih memungkinkan integrasi Anda berfungsi
2. Pemutakhiran Teratur: Pemutakhiran kunci API secara berkala menggunakan fitur regenerasi
3. Penggunaan Penyimpanan yang Aman: Simpan kunci API dengan aman dan jangan pernah mengkomitkannya ke pengaturan versi
4. Penggunaan Kunci Hash: Buat kunci hash yang aman untuk integrasi produksi
5. Pengaturan Masa Berlaku: Selalu atur tanggal berlaku pada kunci yang digunakan untuk akses sementara atau akses CI/CD
6. Penggunaan Kunci yang Terbatas: Batasi kunci untuk aplikasi tertentu dengan peran yang diperlukan minimal

Penggunaan Umum

1. Pengintegrasian CI/CD: Buat kunci yang terbatas pada aplikasi tertentu dengan app_uploader atau app_developer Fungsi, dan atur tanggal kadaluarsa
2. Automasi Pengembangan: Gunakan kunci dengan app_developer Fungsi untuk skrip otomatisasi pengembangan
3. Alat Pemantauan: Buat kunci dengan app_reader Fungsi untuk integrasi pemantauan eksternal
4. Akses Admin: Gunakan kunci dengan org_admin Fungsi dengan hati-hati untuk alat administratif
5. Integrasi Pihak Ketiga: Buat kunci yang terbatas pada aplikasi tertentu dengan peran yang diperlukan minimal
6. 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-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 di Autentikasi Dua Faktor, dan SSO (Perusahaan) untuk detail implementasi di SSO (Perusahaan).