Kunci API

Kunci API digunakan untuk mengautentikasi permintaan ke Capgo API. Kunci-kunci ini spesifik organisasi dan dapat diberi peran RBAC untuk kontrol akses yang 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

Masukkan kunci API Anda di x-api-key header setiap permintaan:

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

Kunci authorization header juga diterima tetapi sebagian besar dimaksudkan untuk token JWT. Ketika nilai adalah kunci API yang dibentuk dalam format UUID, maka berfungsi, tetapi x-api-key header yang disarankan untuk semua jenis kunci (termasuk kunci yang aman/tidak terenkripsi).

Hak Akses Berdasarkan Peran (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 Mengatur izin dasar kunci di seluruh organisasi (misalnya, org_admin, org_member).
• Peran aplikasi Mengatur izin opsional per aplikasi (misalnya, app_admin, app_developer, app_uploader, app_reader).

Jika kunci API memiliki pengikat peran eksplisit, Hanya pengikat tersebut yang dievaluasi untuk periksa izin. Izin pribadi pemilik kunci tidak diwariskan ke kunci.

Pesan

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

Izin pembuatan organisasi

Sekarang pembuatan organisasi dengan kunci API menggunakan izin global eksplisit: org.create.

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

• Kunci API harus termasuk org.create dalam global_permissions.
• Kunci API yang sama juga harus memiliki ikatan organisasi-scope org_admin atau org_super_admin yang aktif saat ini.
• Kunci API baru tidak menerima org.create oleh default. Aktifkan Izinkan membuat organisasi When 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 masih bisa membuat organisasi.

Ketika kunci API membuat organisasi, Capgo secara otomatis mengasign kunci API yang sama ke org_super_admin pada organisasi yang baru saja dibuat. Hal ini memungkinkan integrasi mengelola organisasi yang baru saja dibuat tanpa perlu pengikatan peran manual yang terpisah.

Jika Anda membuat kunci API melalui API, pastikan global_permissions bersamaan dengan pengikatannya sebagai 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

Ketika membuat kunci yang aman, server menghasilkan bahan kunci dan mengembalikan nilai teks biasa sekali. Hanya hash yang disimpan. Artinya:

• Kunci teks biasa tidak dapat diperoleh setelah pembuatan.
• Penghasilan kembali menghasilkan kunci teks biasa baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Kunci yang dihash dianjurkan untuk penggunaan produksi.

Beberapa organisasi mewajibkan kunci yang dihash melalui enforce_hashed_api_keys kebijakan org.

Masa Berlaku

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

Kebijakan organisasi dapat mewajibkan:

• Masa berlaku wajib (require_apikey_expirationSemua kunci harus memiliki kadaluarsa.
• Maksimum TTL (max_apikey_expiration_daysPraktik Keamanan Terbaik

Bab berjudul “Praktik Keamanan Terbaik”

1. : Berikan peran yang paling terbatas yang masih memungkinkan integrasi Anda berfungsiPenggantian Rutin
2. : Ganti kunci __CAPGO_KEEP_0__ secara berkala menggunakan fitur regenerasi: Rotate your API keys periodically using the regenerate feature
3. : Simpan kunci __CAPGO_KEEP_0__ dengan aman dan tidak pernah komit ke pengendalian versi: Store API keys securely and never commit them to version control
4. Gunakan Kunci yang DihashMembuat kunci yang aman (dihash) untuk integrasi produksi
5. Set Tanggal KadaluarsaMembuat tanggal kadaluarsa untuk kunci yang digunakan untuk akses sementara atau akses CI/CD
6. Penggunaan Ruang LingkupMembatasi kunci untuk aplikasi tertentu dengan peran yang minimal

Penggunaan Umum

1. Pengintegrasian CI/CDMembuat kunci yang terbatas pada aplikasi tertentu dengan peran dan tanggal kadaluarsa app_uploader atau app_developer Peran, dan tanggal kadaluarsa
2. Automasi Pengembangan: Gunakan kunci dengan app_developer peran untuk skrip pengaturan otomatis
3. Peralatan Pemantauan: Buat kunci dengan app_reader peran untuk integrasi pemantauan eksternal
4. Akses Administrator: Gunakan kunci dengan org_admin peran dengan sedikit untuk alat administratif
5. Integrasi Pihak Ketiga: Buat kunci yang terbatas pada aplikasi tertentu dengan peran yang diperlukan minimal
6. Penyediaan 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-login-social untuk detail implementasi di @capgo/capacitor-login-social, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-biometrik native untuk detail implementasi di @capgo/capacitor-biometrik native, Autentikasi Dua Faktor untuk detail implementasi di Autentikasi Dua Faktor, dan SSO (Perusahaan) untuk detail implementasi di SSO (Perusahaan).