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.

Tim CapiMailTerbit 2 menit baca
Daftar isi
  1. Alur dalam dua panggilan
  2. Panjang kode, masa berlaku, dan percobaan
  3. Memakai desain email sendiri
  4. Perlindungan bawaan
  5. Menguji seluruh alur di CI
  6. Biaya

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

  1. Backend memanggil POST /api/v1/otp dengan alamat penerima. CapiMail membuat kode angka, mengirimnya dari domain terverifikasi Anda, dan hanya menyimpan hash kode tersebut.
  2. Backend menyimpan id yang dikembalikan, misalnya di sesi login.
  3. Saat pengguna mengetik kode, backend memanggil POST /api/v1/otp/{id}/verify. Jawabannya selalu HTTP 200 dengan valid true atau false.
Mengirim dan memverifikasi OTP dengan SDK TypeScript· ts
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.

FieldRentangDefault platform
code_length4 sampai 10 digit6 digit
ttl_seconds60 sampai 3600 detik10 menit
max_attempts1 sampai 10 kode salah sebelum terkunci5

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 purpose setiap 15 menit. Lebih dari itu dijawab 429 otp_rate_limited dengan header Retry-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.

Test integrasi dengan key cm_test_· ts
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.

Semua artikel