Lewati ke konten utama

Conventional Login Flow

Dokumentasi ini menjelaskan secara rinci urutan pemanggilan API (API call sequence) yang harus diimplementasikan oleh Frontend (FE) untuk fitur otentikasi menggunakan kredensial standar (Email dan Password).

Diagram Alur (Sequence Diagram)​

Berikut adalah urutan proses antara Pengguna, Frontend, dan Backend.

Urutan Integrasi API untuk Frontend​

Step 1: Submit Kredensial​

Saat pengguna menekan tombol Login, Frontend harus mengirimkan data kredensial ke Backend.

Request
POST /api/auth/login
Content-Type: application/json
Request Body
{
  "email": "user@frogcloud.com",
  "password": "Password123!"
}

Kondisi & Error Handling (Step 1):

  • Kondisi A (Sukses Penuh): Backend mengembalikan 200 OK dan struktur data berisi redirect (misalnya /dashboard). Backend juga mengirimkan HTTP-Only Cookies. Frontend langsung mengalihkan pengguna ke Dashboard.
    Response 200 OK (Sukses Langsung)
    {
      "message": "Login successfully",
      "data": {
        "redirect": "/dashboard"
      }
    }
  • Kondisi B (Butuh OTP): Backend mengembalikan 200 OK namun struktur data berisi email dan name (OTP Required). Frontend jangan redirect ke Dashboard, melainkan tampilkan halaman/modal input OTP.
    Response 200 OK (Butuh OTP)
    {
      "message": "OTP has been sent to your email",
      "data": {
        "email": "user@frogcloud.com",
        "name": "John Doe"
      }
    }
  • Error Handling: Jika mengembalikan 400 Bad Request (Validasi Gagal) atau 401 Unauthorized (Email/Password Salah), tangkap message dari backend dan tampilkan sebagai alert atau teks merah pada form input.

Step 2 (Kondisional): Verifikasi OTP​

Langkah ini hanya dilakukan jika Step 1 menghasilkan Kondisi B (Butuh OTP). Pengguna akan menerima OTP di email mereka.

Request
POST /api/auth/otp/verify
Content-Type: application/json
Request Body
{
  "email": "user@frogcloud.com",
  "code": "123456"
}

Kondisi & Error Handling (Step 2):

  • Kondisi Sukses: Backend memvalidasi OTP dan mengembalikan 200 OK beserta Cookies sesi otentikasi. Frontend dapat melanjutkan alihan (redirect) ke Dashboard.
    Response Sukses (200 OK)
    {
      "message": "OTP verified successfully",
      "data": {
        "redirect": "/dashboard"
      }
    }
  • Error Handling: Jika mengembalikan 400 Bad Request (misal: "Invalid or expired OTP code"), biarkan pengguna di halaman OTP dan tampilkan pesan bahwa kode salah atau kadaluarsa. Minta pengguna menginput ulang atau meminta OTP baru.

Manajemen OTP (Resend & Timer)​

Untuk menghindari spam pengiriman email, Backend mengimplementasikan jeda waktu (misal: 60 detik) sebelum Pengguna bisa meminta OTP baru. Frontend harus menampilkan Countdown Timer (Hitung Mundur).

Mendapatkan Sisa Waktu (Remaining Time)

Request
GET /api/auth/otp/remaining

Respons (200 OK): Mengembalikan "remaining_seconds": 45. FE menggunakan angka ini untuk memulai hitung mundur 00:45.

Meminta Ulang OTP (Resend) Jika sisa waktu sudah 0, Pengguna bisa menekan tombol "Kirim Ulang Kode".

Request
POST /api/auth/otp/request
Content-Type: application/json
Request Body
{
  "email": "user@frogcloud.com"
}