Praktik terbaik Verify

Verify dilengkapi default yang cocok untuk sebagian besar alur kode verifikasi sekali pakai. Panduan ini membahas keputusan yang tidak ditentukan oleh default: berapa lama kode harus berlaku, berapa digit yang diperlukan, kanal mana yang sesuai untuk apa yang sebenarnya Anda verifikasi, dan cara membedakan masalah pengiriman dari masalah verifikasi.

Jika suatu standar publik memiliki pandangan, panduan ini mengutipnya. Standar untuk autentikasi kode verifikasi adalah NIST SP 800-63B, Digital Identity Guidelines: Authentication and Authenticator Management, diakses 3 September 2026. Kutipan diambil dari revisi terkini. Revision 3 yang lebih lama dan masih banyak dikutip dalam saran OTP memuat banner NIST sendiri: digantikan oleh SP 800-63-4 per 1 Agustus 2025.

Gunakan kode enam digit atau lebih

Panjang kode default Bird memenuhi NIST SP 800-63B, sementara options.code_length juga menerima kode yang lebih pendek (Opsi). Untuk autentikasi, pertahankan default atau gunakan yang lebih panjang:

The verifier SHALL generate random authentication secrets that are at least six decimal digits (or equivalent) in length using an approved random bit generator

Kode 4 atau 5 digit berada di dalam rentang yang diterima API tetapi di luar yang diizinkan standar. Perpendek kode hanya untuk alur di mana Anda sudah memutuskan bahwa entropi kode verifikasi bukan yang menjalankan fungsi keamanan.

Batasi masa berlaku pada sepuluh menit atau kurang

Duration default berada tepat di batas atas standar, sementara pengaturan workspace menerima jendela waktu yang lebih panjang (Pengaturan verifikasi):

In all cases, the authentication SHALL be considered invalid unless completed within 10 minutes.

Menaikkan Duration melebihi 10 menit untuk mengurangi kontak dukungan tentang kode kedaluwarsa adalah satu-satunya perubahan pengaturan yang diam-diam membawa alur keluar dari 800-63B. Jika kode kedaluwarsa sebelum pengguna sempat membacanya, perbaikannya biasanya ada di jalur pengiriman, bukan di jendela waktunya.

Siapkan dua lapisan pembatasan laju permintaan

Upaya pengecekan dibatasi dua kali, dan kedua batas tersebut menjawab ancaman yang berbeda.

Pengaturan Anda. Maximum Retries membatasi berapa banyak pengecekan salah yang diterima suatu verifikasi sebelum gagal dengan attempts_exhausted (Pengaturan verifikasi). Standar mewajibkan batas ini ada untuk kode sependek ini, dan menambahkan aturan yang perlu diketahui:

Generating a new authentication secret SHALL NOT reset the failed authentication count.

Batas tersebut memiliki plafon, dan ini satu-satunya tempat di mana setiap nilai yang ditawarkan Verify berada dengan nyaman di dalam standar:

the verifier SHALL limit consecutive failed authentication attempts using a specific authenticator on a single subscriber account to no more than 100 by disabling that authenticator

Karena Maximum Retries dibatasi jauh di bawah 100, tidak ada konfigurasi yang bisa Anda pilih yang melampaui batas atas standar. Ini kebalikan dari dua bagian di atas: panjang kode dan durasi masing-masing memiliki nilai yang didukung tetapi keluar dari 800-63B, sedangkan batas upaya tidak.

Batas platform Bird, yang berlaku apa pun konfigurasi Anda: batas pengiriman per jam per penerima (untuk pembuatan dan pengiriman ulang) dan batas pengecekan per menit sama-sama mengembalikan 429 dengan header Retry-After (Perlindungan penyalahgunaan). Batas ini ada untuk mencegah lalu lintas OTP dijadikan senjata terhadap anggaran Anda atau perangkat orang lain, jadi perlakukan 429 di sini sebagai sistem yang bekerja sebagaimana mestinya, bukan sebagai batas yang perlu disiasati.

Pilih kanal sesuai yang Anda verifikasi

Verify mengirim melalui email, SMS, WhatsApp, Telegram, dan voice (Kanal). Standar memperlakukan dua di antaranya secara sangat berbeda, dan perbedaannya terletak pada tujuan kode, bukan kanal yang membawanya.

Email bukan faktor autentikasi. 800-63B bersifat kategoris:

Email SHALL NOT be used for out-of-band authentication because it may be vulnerable to:

• Access using only a password
• Interception in transit or at intermediate mail servers
• Rerouting attacks, such as those caused by Domain Name System (DNS) spoofing

Bagian yang sama mengecualikan kasus yang memang dirancang untuk kanal email Verify:

Confirmation codes that are sent to validate email addresses or are issued as recovery codes (see Sec. 4.2.1.2) are not authentication processes and not affected by the above prohibition.

Jadi kode email yang membuktikan seseorang menguasai suatu alamat berada dalam cakupan pengecualian standar dan sah. Kode email yang digunakan sebagai faktor kedua saat masuk tidak sah. Jika alur Anda yang kedua, jangan gunakan kanal email.

SMS dan voice diizinkan tetapi dibatasi. Pengiriman melalui jaringan telepon membawa tiga kewajiban, dalam dua kalimat berurutan:

Accordingly, verifiers SHALL ensure that alternative authenticator types are available to all subscribers and SHOULD remind subscribers of this limitation of PSTN out-of-band authenticators before binding one or more devices controlled by the subscriber. Verifiers SHOULD consider risk indicators (e.g., device swap, SIM change, number porting, other abnormal behavior) before using the PSTN to deliver an out-of-band authentication secret.

SHALL adalah persyaratan produk, bukan pengaturan Verify: jika SMS adalah satu-satunya faktor Anda, Anda tidak memenuhinya. Urutan kanal per negara di Verify membantu pengiriman, karena WhatsApp dicoba lebih dulu di sebagian besar negara dengan SMS sebagai cadangan (Kanal). Namun, SMS, WhatsApp, Telegram, dan panggilan voice semuanya adalah jalur pengiriman untuk satu tipe autentikator, yaitu out-of-band, sehingga berpindah di antaranya bukan berarti menawarkan tipe alternatif. Dua SHOULD lainnya diimplementasikan oleh tim produk: catatan saat pengguna mengikat nomor telepon, dan pemeriksaan sinyal porting dan pergantian SIM sebelum mengirim ke nomor tersebut.

Baca kegagalan sebelum Anda mengirim ulang

Kode yang tidak sampai dan kode yang sampai tetapi salah ketik memerlukan penanganan berbeda, dan event membedakan keduanya (Event).

verify.attempt.undelivered membawa reason, dan apa yang terjadi selanjutnya bergantung pada rencana kanal penerima. Pada penerima dengan lebih dari satu kanal tersedia, ini tidak mengakhiri verifikasi: Bird melanjutkan ke kanal berikutnya, yang mendapat verify.attempt.sent sendiri, sehingga satu upaya yang tidak terkirim bukan verifikasi mati dan tidak memerlukan pengiriman ulang dari Anda. Pada penerima dengan satu kanal, tidak ada kanal lanjutan, dan verifikasi berakhir.

Akhir tersebut memerlukan penanganan tersendiri, dan satu event mengidentifikasinya. Status failed bersifat bersama: verifikasi masuk ke sana baik ketika terlalu banyak kode verifikasi salah dikirimkan, dengan reason attempts_exhausted, maupun ketika tidak ada kanal yang direncanakan berhasil mengirimkan, dengan reason undeliverable. Hanya yang kedua yang memancarkan verify.verification.failed. Jadi pada penerima dengan satu kanal, event itulah, bukan statusnya, yang memberi tahu Anda bahwa tidak ada yang menerima kode.

Satu properti yang perlu dirancang sejak awal, dan ini milik Bird sendiri, bukan dari standar: Event menyatakan bahwa laporan pengiriman bersifat indikatif, bukan dijamin, karena operator dan penyedia kotak masuk berbeda-beda dalam apa yang mereka konfirmasi dan seberapa cepat. Di beberapa pasar, event upaya tiba terlambat beberapa menit atau tidak membedakan pengiriman dari penerimaan. Bangun jalur "I didn't get a code" berdasarkan POST /v1/verify/verifications/next-channel, yang melanjutkan verifikasi, bukan berdasarkan menunggu event pengiriman yang mungkin tidak datang.

Coba lagi permintaannya, bukan verifikasinya

Ketiga endpoint Verify menerima Idempotency-Key (Mencoba lagi dengan aman). Setelah timeout atau koneksi terputus, mencoba lagi dengan kunci yang sama memutar ulang respons asli: tidak ada kode kedua yang terkirim dan tidak ada upaya pengecekan yang terpakai. Tanpa kunci, percobaan ulang setelah respons hilang mengirim kode lain dan menghabiskan satu pengiriman dari batas per jam.

Ketahui biaya setiap pengiriman

Tagihan melekat pada setiap kode yang dikirim, sesuai tarif kanal untuk tujuan tersebut, dan pengiriman ulang atau fallback menambah biaya per pengiriman (Biaya dan penagihan). Dua konsekuensi membentuk kebijakan percobaan ulang:

• Verifikasi yang melewati beberapa kanal menimbulkan biaya beberapa pengiriman, sehingga rencana kanal yang luas adalah keputusan biaya sekaligus keputusan pengiriman.
• Telegram menagih ketika nomor yang dapat dijangkau diterima untuk pengiriman, bukan berdasarkan tanda terima pengiriman (Biaya dan penagihan). Karena itu, upaya Telegram yang kemudian tidak terkirim tetap ditagih ketika sesi beralih ke kanal berikutnya. Keluarkan Telegram dari urutan kanal di halaman Destinations untuk tujuan yang ingin Anda hindarkan dari biaya fallback tersebut.

Langkah selanjutnya

• Mengirim verifikasi: pengaturan, perlindungan, dan daftar status lengkap
• Event: setiap event sesi dan pengiriman beserta payload-nya
• Destinations: urutan dan ketersediaan kanal per negara
• Pengirim dan branding: tampilan setiap pesan