Pengirim terjadwal harus tetap berfungsi ketika karyawan yang mengonfigurasinya keluar. Alat yang bertindak atas nama karyawan tersebut membutuhkan akses yang mengikuti izin mereka.
Pilih kredensial berdasarkan kepemilikan tersebut. Jauhkan kedua jenis kredensial dari kode browser dan log karena siapa pun yang memilikinya dapat mencoba permintaan yang terautentikasi.
Apa yang bisa dilakukan masing-masing kredensial?
Kunci API bertindak untuk workspace. Token OAuth memungkinkan alat yang diotorisasi bertindak untuk seseorang.
Kunci Bird API diawali dengan bk_. Izinnya milik workspace, sehingga menghapus pembuatnya tidak membatalkan kunci tersebut. Berikan hanya scope yang dibutuhkan layanan untuk membatasi apa yang dapat dilakukan kunci jika terekspos.
Kunci tidak dapat melakukan operasi tingkat organisasi, seperti mengelola anggota organisasi atau billing. Menambahkan lebih banyak scope workspace tidak menghapus batasan tersebut.
Saat Anda masuk melalui server CLI atau MCP, Anda mengotorisasi alat dengan sebagian izin Anda. Alat tersebut menerima token bt_ berumur pendek. Alat mengelola pembaruan token sendiri, jadi jangan menyalin token tersebut ke secret manager layanan.
Cabut alat yang diotorisasi melalui Profile > Connected apps. Gunakan autentikasi untuk memilih scope dan membedakan kunci workspace dari hibah personal.
Bagaimana cara merotasi kunci API?
Terbitkan pengganti dan deploy sebelum masa tumpang tindih kunci lama berakhir.
Anda dapat merotasi dari dashboard, dengan bird api-keys rotate, atau melalui alat api_keys_rotate MCP. Rotasi CLI dan MCP memerlukan hibah personal dengan api_keys:write. Kunci API tidak dapat memiliki izin tersebut atau merotasi kunci lain.
Rotasi mengembalikan token pengganti satu kali. Simpan segera karena pembacaan berikutnya tidak dapat memulihkannya. Pengganti mempertahankan nama lama dan pembatasan IP. Pengganti juga mempertahankan izin kecuali Anda memberikan scopes baru.
Atur grace_period untuk mengontrol masa tumpang tindih. Nilai defaultnya adalah 24h, jadi selesaikan deployment dalam satu hari tersebut. Kedaluwarsa lebih awal pada kunci lama tetap berlaku. Rotasi tidak pernah memperpanjangnya.
Gunakan grace_period: "0" ketika kunci yang bocor harus dicabut segera. Validasi yang di-cache masih dapat menerimanya sebentar, seperti dijelaskan di bawah.
- Minta rotasi dan simpan token yang dikembalikan.
- Deploy pengganti ke setiap layanan sebelum masa tumpang tindih berakhir.
- Konfirmasi permintaan yang berhasil dengan pengganti melalui log layanan.
- Biarkan kunci lama kedaluwarsa, atau cabut ketika peralihan selesai.
Referensi rotasi mencakup perintah dan opsinya.
Apa yang bisa salah selama rotasi?
Respons yang hilang dapat membuat Anda memiliki pengganti yang sudah diterbitkan tetapi tokennya tidak pernah disimpan.
Gunakan Idempotency-Key yang sama saat mencoba lagi permintaan rotasi agar Bird dapat memutar ulang responsnya. Kunci hanya dapat dirotasi satu kali. Tanpa idempotency key yang sama, mengulang rotasi mengembalikan 409. Rotasi pengganti untuk perubahan terencana berikutnya.
Kunci yang dicabut tidak dapat dirotasi. Buat kunci baru jika yang asli sudah dicabut.
Pengganti tidak memiliki kedaluwarsa, meskipun kunci aslinya memilikinya. Anda tidak dapat menambahkan kedaluwarsa setelahnya. Buat kunci baru dengan expires_at jika harus berhenti berfungsi pada waktu tertentu.
Untuk deployment dengan durasi yang tidak pasti, buat kunci kedua dan kelola masa tumpang tindih sendiri. Deploy kunci tersebut sebelum mencabut yang asli. Grace period rotasi tidak dapat diperpanjang setelah permintaan dibuat.
Seberapa cepat pencabutan berlaku?
Kunci yang dicabut dapat tetap diterima hingga lima detik selagi validasi yang di-cache kedaluwarsa.
Anggap kunci yang terekspos masih dapat digunakan selama jeda tersebut. Pencabutan bersifat permanen, sehingga kunci yang dicabut tidak dapat diaktifkan kembali. Bird menyimpan catatannya untuk audit.
Gunakan key_prefix atau fingerprint untuk mengidentifikasi kunci dalam percakapan dukungan. Jangan sertakan kredensial lengkap, karena pengidentifikasi tersebut sudah cukup untuk membedakan kunci tanpa memberikan akses.
Kredensial mana yang harus saya pilih?
Pilih berdasarkan siapa pemilik beban kerja dan izin apa yang dibutuhkan.
- Kunci API: layanan yang harus tetap berfungsi secara independen dari pembuatnya.
- Hibah OAuth: CLI atau agen yang bertindak dalam cakupan izin seseorang.
- Rotasi: kunci pengganti yang dapat Anda deploy selama masa tumpang tindih yang diketahui.
- Kunci baru dengan kedaluwarsa: kredensial yang harus berhenti berfungsi pada waktu tertentu.
Singkatnya
Kredensial layanan milik workspace.
Kunci tetap berlaku meskipun pembuatnya keluar. Alat yang menggunakan OAuth bertindak dalam cakupan izin orang yang mengotorisasinya.
Deploy selama masa tumpang tindih rotasi.
Kunci lama tetap berfungsi selama 24 jam secara default, kecuali kedaluwarsanya yang sudah ada lebih awal.
Simpan pengganti saat diterbitkan.
Rotasi mengembalikan token baru satu kali. Gunakan idempotency key yang sama jika Anda mencoba lagi permintaan rotasi.
Pencabutan memiliki jeda propagasi singkat.
Validasi yang di-cache dapat menerima kunci yang dicabut hingga lima detik, jadi perhitungkan jeda tersebut setelah kebocoran.