Autentikasi API

Semua API RetailOS menggunakan JWT (JSON Web Token) untuk autentikasi. Halaman ini menjelaskan cara mendapatkan dan menggunakan token.

Contoh Login

cURL

curl -X POST https://api.retailos.id/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@toko.com", "password": "xxx"}'

JavaScript

const res = await fetch('https://api.retailos.id/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'admin@toko.com', password: 'xxx' })
})

Go

resp, err := http.Post("https://api.retailos.id/auth/login",
  "application/json",
  strings.NewReader(`{"email":"admin@toko.com","password":"xxx"}`))

Mendapatkan Token

Login

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin@retailmart.co.id",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600,
    "user": {
      "id": "usr-001",
      "name": "Admin",
      "role": "admin",
      "store_id": "STORE-001"
    }
  }
}

Menggunakan Token

Sertakan token di header Authorization:

GET /api/products
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Refresh Token

Token expired setelah 1 jam. Gunakan refresh token untuk mendapatkan token baru:

POST /api/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

WebAuthn (Passwordless)

Untuk POS dan Store Admin, RetailOS mendukung WebAuthn (fingerprint/biometrik):

1. User mendaftarkan perangkat biometrik (satu kali)
2. Login selanjutnya menggunakan fingerprint/face ID
3. Token JWT sama dengan login password

Otorisasi Role

Role	Akses API
admin	Semua endpoint
ho_finance	Cloud Hub: keuangan, settlement, laporan
ho_purchasing	Cloud Hub: PO, supplier, receiving
store_manager	Store Router: semua endpoint toko
cashier	Store Router: POS, member (terbatas)
warehouse_staff	Store Router: inventori, receiving

Catatan

Token yang dikeluarkan oleh Store Router hanya valid untuk Store Router tersebut. Token Cloud Hub tidak bisa digunakan di Store Router dan sebaliknya.

FAQ

Q: Berapa lama token berlaku? A: Access token 1 jam, refresh token 7 hari.

Q: Bagaimana jika token dicuri? A: Segera ganti password. Admin bisa me-revoke semua token user melalui portal admin.