API Kunci

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

Menggunakan kunci API

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

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

The authorization Kepala juga dapat diterima tetapi sebagian besar dimaksudkan untuk token JWT. Ketika nilai adalah kunci UUID-berformat API itu berfungsi, tetapi x-api-key adalah kepala yang disarankan untuk semua jenis kunci (termasuk kunci yang aman/dicetak ulang).

Izin RBAC

API kunci 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 — 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 sebuah kunci API memiliki pengikat peran eksplisit, hanya pengikat-pengikat tersebut yang dievaluasi untuk pengecekan izin. Izin pribadi pemilik kunci tidak diwarisi oleh kunci.

Catatan

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

Kunci yang Aman (Ditambah Hash)

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.
• Penghasilan ulang menghasilkan kunci teks sederhana baru (ditampilkan sekali) dan memperbarui hash yang disimpan.
• Kunci yang dihash direkomendasikan untuk penggunaan produksi.

Beberapa organisasi mengenakan kunci dihash melalui enforce_hashed_api_keys kebijakan organisasi.

Masa Berlaku

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

Kebijakan organisasi dapat mengenakan:

• Masa Berlaku Wajib (require_apikey_expirationMasa Berlaku Wajib — Semua kunci baru harus memiliki tenggat waktu.
• Maksimum TTL (max_apikey_expiration_days — Masa 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. Rotasi Teratur: Rotasi kunci API secara berkala menggunakan fitur regenerasi
3. Penyimpanan Aman: Simpan kunci API secara aman dan tidak pernah komit ke pengendalian versi
4. Gunakan 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. Keterbatasan Ruang Lingkup: Batasi kunci pada aplikasi tertentu dengan peran yang minimal

Penggunaan Umum

1. Integrasi CI/CD: Buat kunci yang terbatas pada aplikasi tertentu dengan app_uploader atau app_developer peran, dan atur tanggal kadaluarsa
2. Automasi Pengembangan: Gunakan kunci dengan app_developer peran untuk skrip pengunduhan otomatis
3. Alat Pemantauan: Buat kunci dengan app_reader peran untuk integrasi pemantauan eksternal
4. Akses Admin: Gunakan kunci dengan org_admin peran dengan bijak untuk alat-alat administratif
5. Integrasi Pihak Ketiga: Buat kunci yang terbatas pada aplikasi tertentu dengan peran yang diperlukan minimal