Lewati ke konten utama

Change Email Flow

Dokumentasi ini menjelaskan urutan proses API ketika Customer ingin mengganti Alamat Email utama mereka. Mengingat email adalah identitas login utama pengguna, Frog Cloud menerapkan protokol keamanan 4-Langkah yang mensyaratkan validasi di kotak masuk email lama maupun email baru.

Diagram Alur Ganti Email​

Karena prosesnya memakan waktu lebih lama daripada perubahan data lainnya, Frontend sangat disarankan untuk memisahkan UI menjadi beberapa tahapan (Wizard/Stepper) seperti yang diilustrasikan di bawah ini:

Urutan Integrasi API untuk Frontend​

Catatan Autentikasi: Seluruh endpoint pada proses Ganti Email ini bersifat internal dan wajib membawa Cookies otentikasi.

Step 1: Meminta OTP ke Email Lama (Request)​

Saat pengguna menekan tombol "Ubah Email", Frontend langsung memanggil API ini. API ini tidak memerlukan request body karena akan mengambil data dari Cookies sesi JWT yang sedang aktif.

Request
POST /api/auth/profile/change-email/request
Content-Type: application/json

Kondisi & Tindakan:

  • Sukses (200 OK): Backend berhasil mengirimkan 6-digit OTP ke email lama pengguna. FE harus melakukan transisi layar ke form Input OTP.

Step 2: Verifikasi OTP Email Lama​

Pengguna memasukkan 6-digit OTP yang mereka terima. FE mengirimkannya ke Backend.

Request
POST /api/auth/profile/change-email/verify-old
Content-Type: application/json
Request Body
{
  "code": "123456"
}

Kondisi & Tindakan:

  • Sukses (200 OK): Kode OTP cocok. Backend akan merespons dengan JSON berisi token perantara: { "data": { "token": "..." } }. FE wajib menyimpan token ini di dalam state (memory) dan memunculkan form input untuk memasukkan alamat Email Baru.
  • Error (400 Bad Request): Kode OTP salah. Tampilkan pesan kesalahan.

Pengguna mengetikkan alamat email barunya. FE mengirimkan alamat email tersebut ke Backend, dilampirkan bersama dengan token yang baru saja didapat dari Step 2.

Request
POST /api/auth/profile/change-email/send-new
Content-Type: application/json
Request Body
{
  "token": "token_dari_response_step_2",
  "new_email": "email_baru_saya@example.com"
}

Kondisi & Tindakan:

  • Sukses (200 OK): Backend akan meracik tautan (link) konfirmasi dan mengirimkannya ke new_email. FE harus mengubah tampilannya menjadi halaman instruksi statis (misal: "Silakan periksa kotak masuk email baru Anda untuk mengkonfirmasi perubahan ini").

Step 4: Konfirmasi Akhir (Finalisasi)​

Ketika pengguna mengklik link di kotak masuk email barunya, link tersebut akan membuka aplikasi/web Anda (misal: https://frogcloud.com/profile/verify-email?token=abc123xyz...). FE harus membaca parameter token dari URL (menggunakan Query Param) dan mem-POST-nya ke Backend untuk dieksekusi.

Request
POST /api/auth/profile/change-email/confirm-new
Content-Type: application/json
Request Body
{
  "token": "abc123xyz_token_dari_url"
}

Kondisi & Tindakan:

  • Sukses (200 OK): Eksekusi pergantian email selesai! Backend sekaligus akan membalas dengan Set-Cookie baru (JWT yang memuat identitas email baru). FE dapat me-redirect pengguna kembali ke halaman pengaturan profil tanpa harus menyuruh pengguna login ulang.
  • Error (400 Bad Request): Link tidak valid atau sudah kadaluarsa. Tampilkan pesan error bahwa proses penggantian gagal dan harus diulang dari awal.