Sign inGet Started

Kontrol agen: kunci dengan cakupan terbatas, batas pengeluaran, dan coba lagi yang aman

Agen yang mengirim melalui Bird memegang kredensial dan menggunakan saldo Anda. Lima kontrol membatasi apa yang dapat dilakukannya. Kontrol pertama adalah kredensial itu sendiri. Empat kontrol lainnya hanya berlaku selama kredensial agen tidak dapat mengubahnya, jadi mulailah dari kredensial.

KontrolYang dibatasiYang diterima pemanggil saat mencapai batasYang menetapkannya
KredensialOperasi yang dapat dipanggil agen403Orang yang membuat kunci atau menyetujui proses masuk
Kunci idempotensiPengiriman ganda saat permintaan dicoba lagiRespons asli, diputar ulangPemanggil, pada setiap permintaan
Daftar izin tujuan SMSNegara yang dapat dituju oleh pengiriman SMS API422 SMSDestinationNotEnabledKredensial dengan akses tulis sms_management
Batas pengeluaran harian SMSPengeluaran SMS ke satu negara dalam sehari422 SMSDestinationDailySpendExceededKredensial dengan akses tulis sms_management
Dompet prabayarPengeluaran bayar sesuai pemakaian402 untuk SMS dan WhatsApp. Email berbayar ditagih setelah dikirim.Pemilik organisasi atau admin penagihan

Daftar izin tujuan dan batas pengeluaran harian di halaman ini berlaku untuk SMS. Verify dan Voice masing-masing memiliki pengaturan tujuan sendiri, dengan kondisi awal yang berbeda. Email dan WhatsApp tidak memiliki daftar izin tujuan maupun batas pengeluaran harian, sehingga di sana agen hanya dibatasi oleh cakupan kredensial dan dompet.

Pilih kredensial yang dipegang agen

Agen memanggil Bird dengan salah satu dari dua jenis kredensial. Keduanya berbeda dalam jangkauan aksesnya.

  • Kunci API (bk_) membawa cakupan yang Anda berikan dan terikat pada satu workspace. Kunci ini tidak dapat menerbitkan kunci lain, dan tidak dapat mengakses penagihan, anggota, atau pengaturan organisasi. Kode Anda mengirimkannya sebagai bearer token. CLI dan server MCP lokal (bird mcp) menggunakan kunci di BIRD_API_KEY jika diatur, alih-alih login yang tersimpan.
  • Token OAuth (bt_) adalah kredensial yang dipegang CLI dan server MCP setelah seseorang login. Token ini membawa izin yang disetujui orang tersebut, dan tidak pernah melebihi izin yang dimilikinya. Izin itu dapat mencakup akses tulis api_keys, akses tulis sms_management, dan penagihan organisasi. Agen dengan token seperti itu dapat menerbitkan kunci, mengaktifkan negara, dan menaikkan batas di halaman ini.

Seberapa banyak yang dapat dilakukan token OAuth bergantung pada cara token itu dibuat:

  • bird auth login meminta akses baca saja. --scope meminta kumpulan izin yang Anda sebutkan, dan --yolo meminta semua izin yang dapat Anda delegasikan. Anda menyetujui hasilnya di browser.
  • Klien MCP yang di-hosting dapat meminta semua izin yang dapat Anda delegasikan. Layar persetujuan memungkinkan Anda memilih izin yang akan diberikan. Hapus centang izin yang tidak dibutuhkan agen sebelum Anda menyetujui.
  • Self-serve signup tidak memiliki layar persetujuan. Kredensial yang dibuatnya memegang setiap izin yang dapat didelegasikan oleh pemilik organisasi baru, termasuk penagihan organisasi.

Untuk agen yang berjalan tanpa pengawasan, buat kunci API dengan cakupan terbatas dan berikan kunci itu kepada agen. Simpan sign-in yang lebih luas untuk orang yang mengonfigurasi workspace. Anda dapat mencabut sign-in sebuah alat di Profile > Connected apps. Kunci API dan token OAuth membandingkan kedua jenis kredensial tersebut.

Batasi cakupan setiap kunci pada produk yang dibutuhkannya

Kunci API membawa daftar cakupan, masing-masing berupa area produk pada tingkat read atau write. Kunci yang hanya mengirim SMS memegang sms:write. Permintaan di luar cakupan kunci menghasilkan 403, sehingga kunci yang bocor atau disalahgunakan hanya menjangkau apa yang Anda berikan.

Tiga sifat kunci berlaku apa pun cakupannya:

  • Kunci tidak dapat menerbitkan kunci lain. Menerbitkan dan merotasi kunci memerlukan api_keys:write, yang tidak tersedia untuk kunci API. Seseorang menyetujuinya melalui sesi dashboard atau melalui sign-in CLI atau MCP.
  • Kunci terbatas pada workspace-nya. Kunci tidak dapat menjangkau penagihan, anggota organisasi, atau pengaturan organisasi.
  • Kunci dapat kedaluwarsa. Atur expires_at saat Anda membuatnya, dan kunci akan menghasilkan 401 setelah waktu tersebut. Rotasi atau cabut kunci kapan saja.

Buat kunci di dashboard atau dari terminal. Sign-in CLI hanya dapat memberikan cakupan yang dimilikinya sendiri kepada kunci, sehingga sign-in ini meminta sms:write selain api_keys:write:

Contoh kode
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write

Autentikasi & kunci API berisi tabel cakupan serta membahas kedaluwarsa, rotasi, dan pencabutan.

Coba lagi pengiriman tanpa mengirim dua kali

Agen yang kehilangan respons tidak dapat mengetahui apakah permintaannya diterima. Kirim header Idempotency-Key dengan nilai unik untuk setiap pengiriman yang dimaksud, dan ulangi permintaan yang sama dengan kunci yang sama saat hasilnya tidak diketahui. Bird mengembalikan respons asli dan menerima pesan hanya sekali. Respons yang diputar ulang membawa Idempotency-Replay: true.

Jaminannya adalah satu operasi yang diterima per kunci selama jendela retensi. Jaminan ini mencakup penerimaan oleh API. Pengiriman ke ponsel dilaporkan terpisah, melalui status pesan dan event-nya.

SDK membuat kunci untuk setiap panggilan yang mengubah data dan menggunakannya kembali untuk percobaan ulang otomatisnya. Di CLI, berikan --idempotency-key. Idempotency membahas format kunci, jendela retensi, dan apa yang terjadi jika kunci digunakan kembali untuk permintaan yang berbeda.

Izinkan setiap negara tujuan SMS

Allowlist tujuan SMS menolak secara default. Pengiriman melalui SMS API hanya diteruskan ke negara yang diaktifkan dalam daftar. Jika tidak, pengiriman ditolak dengan 422 SMSDestinationNotEnabled sebelum pengirim ditentukan, sehingga tidak ada pesan yang diterima. Agen yang diarahkan ke negara yang tidak terduga akan ditolak. Ini berlaku untuk pengiriman dari kode Anda sendiri, dari bird sms send, dan dari tool MCP sms_send.

Kode verifikasi tidak menggunakan daftar ini. Verify memiliki daftarnya sendiri di Verify destinations, dan di sana semua negara aktif sejak awal. Karena itu, kredensial dengan akses tulis verify dapat mengirim kode melalui SMS ke negara yang diblokir allowlist ini. Jika agen memegang verify, nonaktifkan juga di halaman tersebut negara yang tidak Anda layani.

Aktifkan negara di SMS > Destinations, dengan bird sms destinations update, atau dengan tool MCP sms_destinations_update:

Contoh kode
bird sms destinations update --destination NL=true

Mengubah allowlist memerlukan scope sms_management pada level write. Kredensial yang hanya memegang sms dapat mengirim ke negara yang sudah aktif, tetapi tidak dapat mengaktifkan negara lain. Berikan sms kepada agen pengirim, dan simpan sms_management untuk kredensial yang mengonfigurasi workspace.

Mengirim SMS menjelaskan kondisi awal allowlist dan cara negara asal ditambahkan.

Batasi pengeluaran harian SMS untuk setiap negara

Setiap negara tujuan dapat memiliki batas pengeluaran harian dalam mata uang wallet Anda. Setelah pengeluaran hari itu ke negara tersebut mencapai batas, pesan baru ke sana ditolak dengan 422 SMSDestinationDailySpendExceeded hingga tengah malam UTC. Batas nol memblokir negara tersebut.

Kode verifikasi yang dikirim melalui SMS ikut dihitung dalam batas. Saat batas tercapai, Verify berhenti mengirim kode melalui SMS ke negara tersebut dan mencoba channel berikutnya yang aktif untuk negara itu. Jika tidak ada channel tersisa, verifikasi gagal dengan 422 NoAvailableChannel.

Atur batas di tiga tempat yang sama dengan allowlist. Perintah ini mengaktifkan Belanda dan membatasinya hingga 25 EUR per hari, di workspace yang wallet-nya menggunakan EUR:

Contoh kode
bird sms destinations update --destination "NL=true;25EUR"

Batas ini tidak presisi. Perubahan batas memerlukan waktu hingga satu menit sebelum berlaku pada pengiriman. Pengeluaran dihitung saat pesan ditagih, sehingga pesan yang sudah diterima dapat membuat total hari itu melampaui batas sebesar biaya pesan tersebut. Tetapkan batas dengan memperhitungkan selisih itu. bird sms destinations list menampilkan batas setiap negara dan penggunaan hari itu terhadap batas tersebut.

Menetapkan batas memerlukan akses tulis sms_management yang sama dengan daftar izin, sehingga kredensial yang hanya memiliki sms tidak dapat menaikkan batasnya sendiri. Mengirim SMS memuat aturan lengkapnya.

Batasi total pengeluaran dengan dompet prabayar

Pengiriman bayar sesuai pemakaian diambil dari dompet prabayar organisasi Anda. Apa yang terjadi saat saldo tidak cukup untuk suatu pengiriman bergantung pada kanalnya:

  • SMS dan WhatsApp ditolak di API dengan 402. Pesan yang sudah diterima saat penagihannya gagal berakhir rejected dan tidak ditagih.
  • Email pada paket Email berbayar ditagih tidak lama setelah dikirim, sehingga saldo dapat sesaat berada di bawah nol. Setelah dompet tidak memiliki saldo atau kredit lagi, email baru ditolak dengan 402 hingga dana ditambahkan.
  • Biaya saat pengiriman yang tidak dapat ditutupi saldo akan dilewati, dan pesan tetap sampai ke penerimanya.

Dompet yang kosong menghentikan pengeluaran berikutnya, tetapi tidak membatasi pengeluaran tepat pada jumlah saldo. Isi dompet dengan cadangan untuk pengiriman yang ditagih setelah diterima. Jika isi ulang otomatis aktif, dompet terisi kembali dari kartu tersimpan saat saldo turun di bawah ambang batas Anda, sehingga saldo saja tidak lagi membatasi pengeluaran agen. Billing & usage adalah sumber aturan ini.

Operasi penagihan memerlukan izin penagihan organisasi, org:billing. Kunci API tidak dapat memiliki izin ini, sehingga tidak ada kunci yang dapat mengisi ulang dompet, mengubah paket, atau membaca penggunaan. Token OAuth dapat memilikinya jika orang yang menyetujui proses masuk memiliki izin tersebut dan memberikan izin organisasi, seperti yang dapat dilakukan pemilik organisasi. Kredensial dari pendaftaran mandiri memilikinya sejak awal. Berikan kunci dengan cakupan terbatas kepada agen yang berjalan tanpa pengawasan, sehingga penambahan dana tetap berada di tangan pemilik anggaran.

Metode pembayaran dan dompet membahas isi ulang, isi ulang otomatis, dan peringatan saldo rendah.

Langkah berikutnya