Autentikasi
Format key zr_, header autentikasi yang dapat dipertukarkan, dan cara menjaga key tetap aman.
Autentikasi pada API inferensi memakai satu API key. Tidak ada client secret terpisah, alur OAuth, atau request bertanda tangan — semuanya, dari panggilan curl sederhana hingga klien SDK produksi, diautentikasi dengan cara yang sama.
Format API key#
Setiap key mengikuti format zr_<public-id>_<secret>. public-id mengidentifikasi key di workspace Anda (misalnya saat mendaftar atau mencabut key), sedangkan secret adalah bagian sensitif yang Anda kirim pada setiap request.
Header autentikasi#
Kirim key Anda lewat salah satu dari dua header yang dapat dipertukarkan berikut:
Authorization: Bearer zr_<public-id>_<secret>x-api-key: zr_<public-id>_<secret>
Praktik terbaik keamanan key#
Sebuah key memberikan wewenang belanja penuh atas akun Anda, jadi perlakukan seperti kredensial root:
| Praktik | Mengapa penting |
|---|---|
| Jangan pernah commit key ke source control atau isu publik | Key yang bocor memungkinkan siapa pun membelanjakan saldo Anda. Perlakukan seperti kata sandi. |
| Simpan key di secret manager | Key bersifat reveal-once, jadi simpan secret di tempat CI dan runtime bisa membacanya — environment variable, AWS Secrets Manager, atau password manager. |
| Satu key per environment atau proyek | Isolasi membuat pencabutan satu key yang bocor tidak menyusahkan tanpa memengaruhi sisanya. |
| Rotasi dengan mencabut lalu membuat key baru | Tidak ada mekanisme mengubah secret di tempat. Pencabutan plus key baru adalah jalur rotasi yang didukung. |
| Segera cabut jika ada dugaan kebocoran | Pencabutan bersifat instan dan menonaktifkan key di mana pun ia dipakai. |
Cara key disimpan#
zrouter hanya menyimpan hash SHA-256 dari key Anda. Secret dalam bentuk teks asli tidak pernah disimpan setelah Anda membuatnya, jadi staf zrouter tidak dapat membaca key Anda. Inilah sebabnya model reveal-once bersifat ketat: jika secret hilang, satu-satunya pemulihan adalah membuat key baru.
Key dapat dibuat dengan masa berlaku (expiry). Setelah kedaluwarsa, key berhenti diautentikasi dan harus diganti.
Jika akun Anda diblokir, request ditolak dengan 401 invalid_api_key yang sama seperti key yang salah atau tidak ada. Responsnya sengaja tidak dapat dibedakan agar tidak membocorkan status akun.
Memilih kredensial yang tepat#
zrouter memakai tiga dunia autentikasi yang terpisah. Ketiganya tidak pernah bisa saling menggantikan:
| Konteks | Kredensial | Dipakai untuk |
|---|---|---|
| API inferensi | Key zr_ (Bearer atau x-api-key) | Memanggil /v1/chat/completions, /v1/responses, dan /v1/messages. |
| API reseller | JWT reseller (Bearer) | Memanggil /api/reseller/* di program reseller. |
| Dashboard / workspace | Session cookie browser | Mengelola key, checkout, dan receipt di aplikasi web; lima endpoint read-only juga menerima key zr_. |