# Autentikasi

Identitas perusahaan sebelum masuk, login per perangkat, logout, lupa dan atur ulang kata sandi.
Konvensi umum (envelope, kode HTTP, format waktu, rate limit) ada di [README.md](README.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /companies/{slug}/branding`, `POST /auth/login`, `POST /auth/logout`, `POST /auth/forgot-password`, `POST /auth/reset-password` |
| Sumber kode | `AuthController`, `CompanyBrandingController`, `PasswordResetController`, `LoginRequest`, `ForgotPasswordRequest`, `ResetPasswordRequest`, `EmployeeResource`, `EmployeeDeviceResource` |
| Contoh direkam | 2026-10-21, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan (`nusantara-logistik` WIB, `borneo-retail` WITA), `APP_LOCALE=id` seperti server |
| Token pada contoh | **Disamarkan** menjadi `{id}\|contohTokenDisamarkanTidakBerlakuDiServerManaPun`. Nilai aslinya berasal dari basis data uji yang sudah dihapus. Token samaran ini dijawab 401 oleh server lokal dan produksi |

---

## Enum

### `DevicePlatform` (`device_platform`, `device.platform`)

| Nilai | Label |
|---|---|
| `ANDROID` | Android |
| `IOS` | iOS |

### `DeviceStatus` (`device.status`)

| Nilai | `status_label` | Arti bagi client |
|---|---|---|
| `APPROVED` | Disetujui | perangkat boleh dipakai, login menerbitkan token |
| `PENDING` | Menunggu Persetujuan | login ditolak 403 sampai Admin HR menyetujui |
| `REVOKED` | Dicabut | login ditolak 403; token perangkat ini sudah dihapus |

### `EmploymentStatus` (`employee.employment_status`)

| Nilai | `employment_status_label` |
|---|---|
| `PERMANENT` | Karyawan Tetap |
| `CONTRACT` | Karyawan Kontrak |
| `PROBATION` | Masa Percobaan |
| `INTERNSHIP` | Magang |
| `OUTSOURCE` | Alih Daya |
| `FREELANCE` | Pekerja Lepas |

### `WorkPattern` (`employee.work_pattern`)

| Nilai | `work_pattern_label` | Dampak pada presensi |
|---|---|---|
| `FIXED` | Jam Tetap | geofence berlaku |
| `SHIFT` | Shift Bergilir | geofence berlaku, shift boleh melewati tengah malam |
| `FLEXIBLE` | Jam Fleksibel | geofence berlaku |
| `FIELD` | Kerja Lapangan | geofence berlaku |
| `REMOTE` | Kerja Jarak Jauh | pemeriksaan radius dilewati; ambang akurasi GPS tetap berlaku |

---

## Identitas perusahaan

**`GET /companies/{slug}/branding`**

Deskripsi: mengambil nama, logo, dan zona waktu perusahaan berdasarkan kode perusahaan (slug). Dipakai
client untuk menampilkan logo perusahaan di layar login sebelum karyawan masuk. Login sendiri **tidak**
membutuhkan slug.

| Auth & Middleware | |
|---|---|
| Token | publik |
| Middleware | `throttle:api` |
| Route name | `api.v1.companies.branding` |

**Header:** `Accept: application/json`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan validasi |
|---|---|---|---|---|
| `slug` | path | string | ya | dicocokkan persis dengan `companies.slug` perusahaan **aktif**; tidak ada FormRequest |

**Contoh Request**

```http
GET /api/v1/companies/nusantara-logistik/branding HTTP/1.1
Accept: application/json
```

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Identitas perusahaan berhasil diambil.",
  "data": {
    "uuid": "01a15ca1-1f9c-710c-bf21-daafa03f60c9",
    "slug": "nusantara-logistik",
    "name": "Nusantara Logistik",
    "logo_url": null,
    "logo_version": null,
    "timezone": "Asia/Jakarta"
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `uuid` | string (UUID) | tidak | pengenal tetap perusahaan |
| `slug` | string | tidak | kode perusahaan, sama dengan yang diminta |
| `name` | string | tidak | nama tampilan perusahaan |
| `logo_url` | string (URL) | ya | URL bertanda tangan, **berlaku 120 menit**. `null` bila perusahaan belum mengunggah logo. Jangan disimpan sebagai alamat tetap |
| `logo_version` | string | ya | berubah setiap kali logo diganti. Pakai sebagai kunci cache gambar; unduh ulang hanya bila nilainya berubah |
| `timezone` | string (IANA) | tidak | zona waktu perusahaan, mis. `Asia/Jakarta`, `Asia/Makassar`, `Asia/Jayapura` |

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Slug tidak ada atau perusahaan tidak aktif | 404 | `Kode perusahaan tidak ditemukan.` |
| Lebih dari 60 permintaan per menit dari IP yang sama | 429 | `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` |

```json
{
  "success": false,
  "message": "Kode perusahaan tidak ditemukan.",
  "errors": {}
}
```

**Catatan**

- Idempotency: tidak relevan (GET).
- Rate limit: `api`, 60 per menit per IP. Respons membawa `X-RateLimit-Limit: 60` dan
  `X-RateLimit-Remaining`.
- FeatureGate / modul: tidak ada.
- Status langganan: tidak diperiksa (endpoint publik).

---

## Login

**`POST /auth/login`**

Deskripsi: memeriksa Nomor Karyawan atau surel beserta kata sandi, mendaftarkan atau mengenali
perangkat, lalu menerbitkan token Sanctum untuk perangkat itu. Dipanggil dari layar login.

| Auth & Middleware | |
|---|---|
| Token | publik |
| Middleware | `throttle:login` |
| Route name | `api.v1.auth.login` |

**Header:** `Accept: application/json`, `Content-Type: application/json`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `identifier` | body | string | ya | `required`, `string`, `max:255`. Nomor Karyawan **atau** alamat surel |
| `password` | body | string | ya | `required`, `string` |
| `device_identifier` | body | string | ya | `required`, `string`, `max:255`. Pengenal unik dan **stabil per instalasi** aplikasi |
| `device_platform` | body | string (enum) | ya | `required`, `Rule::enum(DevicePlatform)`: `ANDROID` atau `IOS` |
| `device_name` | body | string | tidak | `nullable`, `string`, `max:255`. Nama model perangkat untuk ditampilkan ke Admin HR, mis. `Google Pixel 8` |
| `app_version` | body | string | tidak | `nullable`, `string`, `max:50`. Versi aplikasi, mis. `1.0.1`. Disimpan pada data perangkat; belum dipakai untuk memaksa pembaruan |

**Contoh Request**

```http
POST /api/v1/auth/login HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "identifier": "citra@nusantara-logistik.test",
  "password": "Rahasia123!",
  "device_identifier": "6f1c2a9e-4b7d-4e21-9a51-citra-pixel8",
  "device_platform": "ANDROID",
  "device_name": "Google Pixel 8",
  "app_version": "1.0.0"
}
```

**Contoh Response Sukses** (`200`, perangkat pertama karyawan)

```json
{
  "success": true,
  "message": "Perangkat berhasil didaftarkan.",
  "data": {
    "token": "1|contohTokenDisamarkanTidakBerlakuDiServerManaPun",
    "employee": {
      "id": 3,
      "employee_number": "EMP-0007",
      "name": "Citra Satu",
      "email": "citra@nusantara-logistik.test",
      "phone": "081234560007",
      "employment_status": "OUTSOURCE",
      "employment_status_label": "Alih Daya",
      "work_pattern": "FIXED",
      "work_pattern_label": "Jam Tetap",
      "department": "Divisi Operasional",
      "position": "Spesialis",
      "job_level": "Direktur",
      "must_change_password": false
    },
    "device": {
      "id": 1,
      "device_identifier": "6f1c2a9e-4b7d-4e21-9a51-citra-pixel8",
      "device_name": "Google Pixel 8",
      "platform": "ANDROID",
      "status": "APPROVED",
      "status_label": "Disetujui",
      "approved_at": "2026-10-21T00:40:00+00:00",
      "last_used_at": "2026-10-21T00:40:00+00:00"
    }
  }
}
```

Login ulang dari perangkat yang sama satu menit kemudian (`app_version` naik ke `1.0.1`) menjawab
`200` dengan `"message": "Perangkat dikenali."`, token baru `2|...`, dan
`"last_used_at": "2026-10-21T00:41:00+00:00"`. Token lama `1|...` langsung dijawab **401** oleh
`GET /me`.

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `token` | string | tidak | Bearer token, bentuk `{id}\|{48 karakter}`. Perlakukan sebagai teks utuh; simpan terenkripsi (mis. EncryptedSharedPreferences). Tidak kedaluwarsa sampai dicabut |
| `employee` | objek | tidak | data karyawan, sama persis dengan `GET /me` ([me.md](me.md#profil-karyawan)) |
| `employee.id` | integer | tidak | ID karyawan |
| `employee.employee_number` | string | tidak | Nomor Karyawan |
| `employee.name` | string | tidak | nama lengkap |
| `employee.email` | string | ya | surel karyawan |
| `employee.phone` | string | ya | nomor telepon |
| `employee.employment_status` | string (enum) | tidak | `EmploymentStatus` |
| `employee.employment_status_label` | string | tidak | label Bahasa Indonesia |
| `employee.work_pattern` | string (enum) | tidak | `WorkPattern` |
| `employee.work_pattern_label` | string | tidak | label Bahasa Indonesia |
| `employee.department` | string | ya | nama departemen |
| `employee.position` | string | ya | nama jabatan |
| `employee.job_level` | string | ya | nama jenjang jabatan |
| `employee.must_change_password` | boolean | tidak | `true` bila kata sandi sementara dari Admin HR; client wajib membuka layar ganti kata sandi (`PUT /me/password`) sebelum fitur lain |
| `device` | objek | tidak | perangkat yang dipakai login |
| `device.id` | integer | tidak | ID perangkat |
| `device.device_identifier` | string | tidak | sama dengan request |
| `device.device_name` | string | ya | nama perangkat |
| `device.platform` | string (enum) | tidak | `DevicePlatform` |
| `device.status` | string (enum) | tidak | selalu `APPROVED` pada login sukses |
| `device.status_label` | string | tidak | `Disetujui` |
| `device.approved_at` | string (ISO 8601 UTC) | ya | waktu perangkat disetujui |
| `device.last_used_at` | string (ISO 8601 UTC) | ya | waktu login terakhir dari perangkat ini |

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Validasi gagal | 422 | `Data yang dikirim tidak lolos pemeriksaan.` |
| Nomor Karyawan/surel tidak ditemukan, kata sandi salah, atau perusahaan tidak aktif | 401 | `Nomor Karyawan atau kata sandi tidak sesuai.` |
| Akun karyawan tidak `ACTIVE` | 403 | `Akun karyawan tidak berstatus aktif. Hubungi Admin HR.` |
| Perangkat lain saat karyawan sudah punya perangkat disetujui (perangkat baru tercatat `PENDING`) | 403 | `Perangkat ini belum disetujui. Pengajuan sudah dikirim ke Admin HR, silakan hubungi Admin HR untuk mempercepat persetujuan.` |
| Perangkat berstatus `REVOKED` | 403 | `Perangkat ini sudah dicabut aksesnya. Hubungi Admin HR bila ingin mendaftarkannya kembali.` |
| Nomor Karyawan dan kata sandi cocok di lebih dari satu perusahaan | 409 | `Nomor Karyawan tersebut terdaftar di lebih dari satu perusahaan. Gunakan alamat surel Anda untuk masuk.` |
| Percobaan keenam dalam satu menit untuk `identifier` + IP yang sama | 429 | `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` |

Validasi (`identifier` terisi, `password` dan `device_identifier` kosong, `device_platform: "WINDOWS"`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "password": [
      "Kolom kata sandi wajib diisi."
    ],
    "device_identifier": [
      "Kolom pengenal perangkat wajib diisi."
    ],
    "device_platform": [
      "Pilihan pada kolom jenis perangkat tidak sah."
    ]
  }
}
```

Perangkat belum disetujui (`device_identifier: "b3d0e8f1-samsung-a55-citra"`, karyawan sudah punya
Pixel 8 yang disetujui). Perangkat yang dicabut memakai bentuk yang sama dengan message `Perangkat ini
sudah dicabut aksesnya. ...`:

```json
{
  "success": false,
  "message": "Perangkat ini belum disetujui. Pengajuan sudah dikirim ke Admin HR, silakan hubungi Admin HR untuk mempercepat persetujuan.",
  "errors": {
    "device": [
      "Perangkat ini belum disetujui. Pengajuan sudah dikirim ke Admin HR, silakan hubungi Admin HR untuk mempercepat persetujuan."
    ]
  }
}
```

Kredensial salah, akun tidak aktif, Nomor Karyawan ganda, dan 429 tidak membawa rincian:

```json
{
  "success": false,
  "message": "Nomor Karyawan tersebut terdaftar di lebih dari satu perusahaan. Gunakan alamat surel Anda untuk masuk.",
  "errors": {}
}
```

**Catatan**

- **Perangkat pertama langsung disetujui.** Bila karyawan belum punya perangkat `APPROVED`, perangkat
  yang dipakai login pertama otomatis `APPROVED`.
- **Satu karyawan satu perangkat.** Login dari perangkat lain mencatat perangkat itu `PENDING` dan
  menjawab 403. Setelah Admin HR menyetujuinya di panel, perangkat lama otomatis `REVOKED` (tokennya
  dihapus) dan login dari perangkat baru berhasil dengan message `Perangkat dikenali.`.
- **Satu token per perangkat.** Login ulang dari `device_identifier` yang sama menghapus token lama
  perangkat itu. Login dari perangkat yang sudah dikenali memperbarui `device_platform`, `device_name`,
  dan `app_version` bila dikirim.
- **Nomor Karyawan ganda lintas perusahaan.** 409 hanya terjadi bila kata sandi cocok di dua
  perusahaan atau lebih. Client menampilkan message dan meminta karyawan memakai surel.
- Karyawan yang ponselnya bermasalah memakai alur perangkat pinjaman (`device-lending.md`), bukan
  login biasa di ponsel rekan.
- Idempotency: tidak ada; client mencegah kirim ganda saat request berjalan.
- Rate limit: `login`, 5 per menit per `identifier` + IP. Respons membawa `X-RateLimit-Limit: 5` dan
  `X-RateLimit-Remaining`; 429 membawa `Retry-After` (detik sampai kuota pulih, mis. `60` lalu `25`
  setelah 35 detik) dan `X-RateLimit-Reset`.
- FeatureGate / modul: tidak ada.
- Status langganan: **tidak diperiksa saat login.** Login tetap berhasil walau langganan terkunci;
  client membaca `GET /me/config` → `subscription.is_locked` setelah login.

---

## Logout

**`POST /auth/logout`**

Deskripsi: mencabut token yang sedang dipakai. Bila token itu milik sesi perangkat pinjaman, izin
pinjaman ikut dihentikan. Token perangkat lain milik karyawan tidak tersentuh.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` (dikecualikan saat langganan terkunci) |
| Route name | `api.v1.auth.logout` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`

**Parameter:** tidak ada.

**Contoh Request**

```http
POST /api/v1/auth/logout HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Berhasil keluar.",
  "data": {}
}
```

Dengan token sesi perangkat pinjaman:

```json
{
  "success": true,
  "message": "Berhasil keluar dan izin perangkat pinjaman dihentikan.",
  "data": {}
}
```

**Field `data`:** objek kosong `{}`.

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Token tidak ada, salah, atau sudah dicabut | 401 | `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |

```json
{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}
```

**Catatan**

- Setelah 200, token yang sama dijawab 401 (terekam: `GET /me` sesudah logout → 401).
- Bila logout dijawab 401, token memang sudah tidak berlaku. Client tetap menghapus token lokal dan
  kembali ke layar login.
- Idempotency: memanggil dua kali aman; panggilan kedua dijawab 401.
- Rate limit: tidak ada.
- FeatureGate / modul: tidak ada.
- Status langganan: **tetap 200 saat langganan terkunci.**

---

## Lupa kata sandi

**`POST /auth/forgot-password`**

Deskripsi: meminta kode atur ulang kata sandi 6 digit yang dikirim ke surel karyawan. Jawaban selalu
sama, baik akun ditemukan maupun tidak, agar tidak membocorkan keberadaan akun.

| Auth & Middleware | |
|---|---|
| Token | publik |
| Middleware | `throttle:password-reset` |
| Route name | `api.v1.auth.forgot-password` |

**Header:** `Accept: application/json`, `Content-Type: application/json`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `identifier` | body | string | ya | `required`, `string`, `max:255`. Nomor Karyawan atau surel |

**Contoh Request**

```http
POST /api/v1/auth/forgot-password HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "identifier": "EMP-0003"
}
```

**Contoh Response Sukses** (`200`; identik untuk `identifier` yang tidak terdaftar)

```json
{
  "success": true,
  "message": "Bila Nomor Karyawan atau surel tersebut terdaftar dan memiliki alamat surel, kode atur ulang sudah dikirim. Bila Anda tidak menerima kode, hubungi Admin HR untuk meminta atur ulang kata sandi.",
  "data": {
    "expires_minutes": 15
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `expires_minutes` | integer | tidak | masa berlaku kode dalam menit (bawaan 15). Client menampilkan hitung mundur |

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| `identifier` kosong | 422 | `Data yang dikirim tidak lolos pemeriksaan.` |
| Percobaan keempat dalam satu menit untuk `identifier` + IP yang sama | 429 | `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` |

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "identifier": [
      "Kolom Nomor Karyawan atau surel wajib diisi."
    ]
  }
}
```

**Catatan**

- Kode **hanya** dikirim bila `identifier` cocok dengan **tepat satu** karyawan berstatus `ACTIVE` di
  perusahaan aktif dan karyawan itu punya surel. Nomor Karyawan yang terdaftar di dua perusahaan tidak
  menerima kode; arahkan karyawan memakai surel.
- Meminta kode baru membatalkan kode sebelumnya yang belum dipakai.
- Idempotency: tidak ada. Setiap panggilan yang lolos syarat mengirim surel baru.
- Rate limit: `password-reset`, 3 per menit per `identifier` + IP (berbagi kuota dengan
  `POST /auth/reset-password`).
- FeatureGate / modul: tidak ada.
- Status langganan: tidak diperiksa.

---

## Atur ulang kata sandi

**`POST /auth/reset-password`**

Deskripsi: mengganti kata sandi memakai kode dari surel. Setelah berhasil, **seluruh** token karyawan
dicabut dan client kembali ke layar login.

| Auth & Middleware | |
|---|---|
| Token | publik |
| Middleware | `throttle:password-reset` |
| Route name | `api.v1.auth.reset-password` |

**Header:** `Accept: application/json`, `Content-Type: application/json`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `identifier` | body | string | ya | `required`, `string`, `max:255`. Sama dengan saat meminta kode |
| `code` | body | string | ya | `required`, `string`, `digits:6`. Kirim sebagai teks agar angka nol di depan tidak hilang |
| `password` | body | string | ya | `required`, `string`, `confirmed`, minimal 8 karakter |
| `password_confirmation` | body | string | ya | wajib sama dengan `password` (aturan `confirmed`) |

**Contoh Request**

```http
POST /api/v1/auth/reset-password HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "identifier": "EMP-0003",
  "code": "966072",
  "password": "SandiBaru2026",
  "password_confirmation": "SandiBaru2026"
}
```

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Kata sandi berhasil diatur ulang. Silakan masuk memakai kata sandi baru.",
  "data": {}
}
```

**Field `data`:** objek kosong `{}`.

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Validasi gagal | 422 | `Data yang dikirim tidak lolos pemeriksaan.` |
| Kode salah, kedaluwarsa, sudah dipakai, sudah 5 kali salah, atau `identifier` tidak dikenal | 422 | `Kode atur ulang tidak sah atau sudah kedaluwarsa. Ajukan kode baru.` |
| Percobaan keempat dalam satu menit untuk `identifier` + IP yang sama | 429 | `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` |

Validasi (`code: "12"`, `password: "pendek"`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "code": [
      "Kolom kode atur ulang harus terdiri dari 6 angka."
    ],
    "password": [
      "Kolom kata sandi baru minimal 8 karakter."
    ]
  }
}
```

Kode tidak sah (`code: "000000"`):

```json
{
  "success": false,
  "message": "Kode atur ulang tidak sah atau sudah kedaluwarsa. Ajukan kode baru.",
  "errors": {
    "code": [
      "Kode atur ulang tidak sah atau sudah kedaluwarsa."
    ]
  }
}
```

**Catatan**

- Setiap kode salah menambah hitungan percobaan. Pada percobaan keenam kode dibatalkan walaupun benar;
  karyawan meminta kode baru.
- Setelah 200, token lama karyawan dijawab 401 (terekam: `GET /me` dengan token sebelum atur ulang →
  401). `must_change_password` menjadi `false`.
- Idempotency: kode hanya berlaku sekali. Panggilan kedua dengan kode yang sama dijawab 422.
- Rate limit: `password-reset`, 3 per menit per `identifier` + IP.
- FeatureGate / modul: tidak ada.
- Status langganan: tidak diperiksa.
