Autentikasi

Lihat Markdown

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 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

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 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

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 /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

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 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

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 /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.