OTP lewat API: kirim dan verifikasi kode tanpa menyimpan kode di database Anda
Cara memakai OTP API untuk login, verifikasi email, dan reset PIN: kirim kode dari domain sendiri, verifikasi sekali pakai, batas percobaan, dan uji di CI.
Daftar isi
Membangun OTP sendiri terlihat sederhana: buat angka acak, simpan, kirim email, lalu cocokkan. Dalam praktiknya ada banyak detail yang mudah terlewat: menyimpan hash dan bukan kode asli, masa berlaku, batas percobaan salah, kode sekali pakai, dan perlindungan dari email bombing. Panduan ini menunjukkan cara menyerahkan semua itu ke OTP API, sementara backend Anda cukup menyimpan id OTP.
Alur dalam dua panggilan
- Backend memanggil
POST /api/v1/otpdengan alamat penerima. CapiMail membuat kode angka, mengirimnya dari domain terverifikasi Anda, dan hanya menyimpan hash kode tersebut. - Backend menyimpan
idyang dikembalikan, misalnya di sesi login. - Saat pengguna mengetik kode, backend memanggil
POST /api/v1/otp/{id}/verify. Jawabannya selalu HTTP 200 denganvalidtrue atau false.
import { CapiMail } from "@capimail/sdk";
const capimail = new CapiMail({ apiKey: process.env.CAPIMAIL_API_KEY! });
// 1. Kirim kode
const otp = await capimail.otp.send({
to: user.email,
purpose: "login",
locale: "id",
});
await saveLoginChallenge(user.id, otp.id); // simpan id-nya saja
// 2. Verifikasi kode yang diketik pengguna
const result = await capimail.otp.verify(otp.id, typedCode);
if (result.valid) {
await signIn(user.id);
} else {
// status: invalid_code | locked | expired | already_verified | not_found
showError(result.status, result.attemptsRemaining);
}Panjang kode, masa berlaku, dan percobaan
Setiap nilai bisa diatur per permintaan, per domain pengirim di dashboard, atau dibiarkan memakai default. Urutannya: permintaan, lalu pengaturan domain, lalu default workspace, lalu default platform.
| Field | Rentang | Default platform |
|---|---|---|
code_length | 4 sampai 10 digit | 6 digit |
ttl_seconds | 60 sampai 3600 detik | 10 menit |
max_attempts | 1 sampai 10 kode salah sebelum terkunci | 5 |
Kode bersifat sekali pakai: setelah terverifikasi, percobaan berikutnya mendapat status already_verified. Spasi dan tanda hubung pada kode yang diketik pengguna diabaikan.
Memakai desain email sendiri
Tanpa template, CapiMail mengirim email bawaan yang bersih dalam bahasa Indonesia atau Inggris. Untuk desain sendiri, buat template transaksional dengan template_key. Template menerima {{code}}, {{expires_minutes}}, dan {{purpose}}, ditambah variabel apa pun yang Anda kirim lewat variables. Jika workspace punya beberapa domain, setiap domain bisa memakai pengirim, template, dan bahasa yang berbeda.
Perlindungan bawaan
- Batas laju. Maksimal 5 kode per penerima dan
purposesetiap 15 menit. Lebih dari itu dijawab429 otp_rate_limiteddengan headerRetry-After. Ini melindungi pengguna Anda dari email bombing. - Hanya hash yang disimpan. Kode asli tidak disimpan, dan data OTP dihapus setelah 7 hari.
- Aturan pengiriman yang sama. Penerima yang ada di daftar supresi, domain yang belum terverifikasi, dan kredit yang kurang ditolak dengan cara yang sama seperti
POST /api/v1/emails.
Menguji seluruh alur di CI
Dengan key test (cm_test_), OTP tidak pernah dikirim dan tidak memotong kredit, tetapi responsnya menyertakan kode sebagai test_code. Jadi test otomatis Anda bisa menjalankan alur kirim lalu verifikasi tanpa membaca inbox.
const otp = await testClient.otp.send({ to: "qa+login@contoh.co.id", purpose: "login" });
const result = await testClient.otp.verify(otp.id, otp.testCode!);
expect(result.valid).toBe(true);Biaya
1 kredit per kode yang diterbitkan, ditambah kredit kirim email biasa. Verifikasi gratis. Lihat harga add-on dan referensi OTP API. Untuk praktik keamanan isi email OTP dan reset password secara umum, baca juga panduan OTP dan reset password.
Pertanyaan yang sering diajukan
Apakah saya masih perlu menyimpan kode OTP di database?
Tidak. Backend cukup menyimpan id OTP yang dikembalikan saat mengirim. CapiMail menyimpan hash kode dan memverifikasinya sekali.
Bagaimana mencegah satu alamat dibanjiri kode OTP?
OTP API membatasi maksimal 5 kode per penerima dan purpose setiap 15 menit, lalu menjawab 429 otp_rate_limited dengan Retry-After.