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.
| 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
GET /api/v1/companies/nusantara-logistik/branding HTTP/1.1
Accept: application/json
Contoh Response Sukses (200)
{
"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. |
{
"success": false,
"message": "Kode perusahaan tidak ditemukan.",
"errors": {}
}
Catatan
- Idempotency: tidak relevan (GET).
- Rate limit:
api, 60 per menit per IP. Respons membawaX-RateLimit-Limit: 60danX-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
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)
{
"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) |
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"):
{
"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. ...:
{
"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:
{
"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 otomatisAPPROVED. - Satu karyawan satu perangkat. Login dari perangkat lain mencatat perangkat itu
PENDINGdan menjawab 403. Setelah Admin HR menyetujuinya di panel, perangkat lama otomatisREVOKED(tokennya dihapus) dan login dari perangkat baru berhasil dengan messagePerangkat dikenali.. - Satu token per perangkat. Login ulang dari
device_identifieryang sama menghapus token lama perangkat itu. Login dari perangkat yang sudah dikenali memperbaruidevice_platform,device_name, danapp_versionbila 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 peridentifier+ IP. Respons membawaX-RateLimit-Limit: 5danX-RateLimit-Remaining; 429 membawaRetry-After(detik sampai kuota pulih, mis.60lalu25setelah 35 detik) danX-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_lockedsetelah 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
POST /api/v1/auth/logout HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200)
{
"success": true,
"message": "Berhasil keluar.",
"data": {}
}
Dengan token sesi perangkat pinjaman:
{
"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. |
{
"success": false,
"message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
"errors": {}
}
Catatan
- Setelah 200, token yang sama dijawab 401 (terekam:
GET /mesesudah 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
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)
{
"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. |
{
"success": false,
"message": "Data yang dikirim tidak lolos pemeriksaan.",
"errors": {
"identifier": [
"Kolom Nomor Karyawan atau surel wajib diisi."
]
}
}
Catatan
- Kode hanya dikirim bila
identifiercocok dengan tepat satu karyawan berstatusACTIVEdi 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 peridentifier+ IP (berbagi kuota denganPOST /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
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)
{
"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"):
{
"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"):
{
"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 /medengan token sebelum atur ulang → 401).must_change_passwordmenjadifalse. - Idempotency: kode hanya berlaku sekali. Panggilan kedua dengan kode yang sama dijawab 422.
- Rate limit:
password-reset, 3 per menit peridentifier+ IP. - FeatureGate / modul: tidak ada.
- Status langganan: tidak diperiksa.