Auth (login/logout/token)

Dokumen ini menjelaskan endpoint autentikasi utama, lengkap dengan controller, method, payload, dan response.

API v1 — Login

Route

• Method: POST
• Path: /api/auth/login
• Route file: routes/api.php
• Controller: App\Http\Controllers\Api\AuthController@login
• Request validation: App\Http\Requests\Api\LoginRequest
• Middleware: throttle.custom (lihat routes/api.php)

Payload (JSON)

Berdasarkan LoginRequest:

Field	Type	Required	Validasi
email	string	Ya	required, email
password	string	Ya	required
otpCode	string	Tidak	nullable (akan dibutuhkan jika user sudah bind 2FA)

Contoh:

{
  "email": "user@example.com",
  "password": "P@ssw0rd!",
  "otpCode": "123456"
}

Alur sukses

Jika kredensial valid, email sudah terverifikasi, tidak suspend, dan (jika 2FA aktif) otpCode valid:

• server membuat xToken ($user->createToken('xToken'))
• server menyimpan token ke Redis (v1)
• server membuat refreshToken dan simpan ke Redis

Response sukses (200)

Envelope mengikuti sendResponse() (lihat docs/bitwewe/api-conventions).

data berisi gabungan $user->data() plus token:

{
  "code": 200,
  "title": "OK",
  "message": "…",
  "result": true,
  "data": {
    "xToken": {
      "token": "<access_token>",
      "expiresAt": "YYYY-MM-DD HH:mm:ss"
    },
    "refreshToken": "<refresh_token>"
  }
}

Catatan: data juga menyertakan field dari $user->data() (profil user) selain potongan token di atas.

Response gagal yang penting

Kondisi	HTTP	message (trans key)	Catatan
Email/password salah	401	auth.failed	v1 mengirim auth_required=false
Email belum verify	411	auth.verify
User 2FA aktif tapi otpCode kosong	400	auth.otp_required	code default sendError
OTP salah	403	auth.otp_failed
Akun suspend	403	auth.suspend

---

API v1 — Check account (deteksi 2FA)

Route

• Method: POST
• Path: /api/auth/check-account
• Controller: App\Http\Controllers\Api\AuthController@checkAccount
• Request validation: LoginRequest
• Middleware: throttle.custom

Tujuan

• Jika user tidak bind 2FA → server melakukan login langsung (tanpa minta OTP).
• Jika user bind 2FA → server mengembalikan flag agar klien meminta OTP.

Response sukses (200)

Jika butuh 2FA:

{
  "code": 200,
  "title": "OK",
  "message": "…",
  "result": true,
  "data": {
    "user_2fa": true
  }
}

Jika tidak butuh 2FA, response sama seperti login sukses (mengandung xToken dan refreshToken).

---

Catatan implementasi

• Validasi payload dan sanitasi berasal dari Request class (contoh: LoginRequest).
• Semua response mengikuti envelope di docs/bitwewe/api-conventions.