Otentikasi

Pengenalan

Backend API mendukung dua mekanisme otentikasi utama: Bearer Token (JWT) yang diperoleh dari login username/password, dan API Key untuk kebutuhan service-to-service atau automasi. Setiap request ke API harus menyertakan salah satunya. Untuk arsitektur multi-instance (federation), terdapat mekanisme tambahan berupa header X-User-Permissions yang memungkinkan Federation Module meneruskan konteks izin pengguna ke remote instance secara aman tanpa harus replay JWT user asli.

Sesi pengguna kini berbasis server (session-backed): setiap login membuat satu record sesi, access_token berumur pendek (30 menit) dan diperbarui lewat refresh_token yang dirotasi setiap kali dipakai. Selain itu, request Bearer Token dari luar dashboard dilindungi integration lock — sehingga jalur yang didukung untuk integrasi pihak ketiga adalah API Key.

Halaman ini mencakup seluruh alur otentikasi secara teknis — cara mendapatkan token, siklus hidup sesi, cara menyertakan kredensial di request HTTP maupun WebSocket, hingga alur federation antar-instance backend.

Tipe Otentikasi

Jalur Mana yang Harus Saya Pakai?

Aturannya sederhana: kalau yang memanggil API bukan manusia yang sedang login di browser, pakai X-Api-Key. Bearer token hanya untuk aplikasi yang menampilkan halaman login Lenz kepada penggunanya sendiri.

curl "${API_URL}/api/streams" -H "X-Api-Key: ${API_KEY}"

curl -X POST "${API_URL}/api/auth/token" -d '{"user_access":"…","password":"…"}'
curl "${API_URL}/api/streams" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "X-Integration-Signature: ${SIG}"

Login Cepat (Untuk Operator)

Jika Anda hanya perlu masuk ke dashboard Lenz, buka browser dan kunjungi alamat Lenz yang sudah dikonfigurasi admin Anda. Masukkan username dan password pada halaman login — tidak diperlukan konfigurasi tambahan.

Login dengan Username & Password

curl -X POST "${API_URL}/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "user_access": "[email protected]",
    "password": "your-password",
    "remember_me": false
  }'

const res = await fetch(`${API_URL}/api/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    user_access: "[email protected]",
    password: "your-password",
  }),
});
const { access_token, refresh_token, name } = await res.json();

import requests

res = requests.post(
    f"{API_URL}/api/auth/token",
    json={"user_access": "[email protected]", "password": "your-password"},
    timeout=10,
)
data = res.json()
access_token = data["access_token"]

{
  "ok": false,
  "code": "active-session-exists",
  "message": "An active session already exists for this account",
  "data": {
    "session_count": 1,
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/126.0",
    "ip_address": "10.0.4.21",
    "last_used_at": "2026-09-16T08:12:44Z"
  }
}

{
  "ok": true,
  "message": "Successfull Login",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "name": "Admin Utama"
}

curl "${API_URL}/api/streams" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Login dengan API Key

API key cocok untuk integrasi backend, skrip otomatis, CI/CD pipeline, atau layanan tanpa konteks pengguna interaktif. API key dibuat oleh admin di Administration → Configuration → API Key pada dashboard Lenz.

Untuk mendapatkan access_token menggunakan API key, kirim POST /api/auth/token tanpa body, namun sertakan header X-Api-Key:

curl -X POST "${API_URL}/api/auth/token" \
  -H "X-Api-Key: YOUR_API_KEY_HERE"

Server mengembalikan respons dalam format yang sama dengan login username/password (HTTP 201). Sesi dari login API key berlaku 7 hari (bukan 1/3 hari), tidak tunduk pada kebijakan satu sesi aktif, dan tidak mengenal remember_me.

curl "${API_URL}/api/streams" \
  -H "X-Api-Key: YOUR_API_KEY_HERE"

Verifikasi Kredensial

Untuk memastikan token atau API key masih diterima, kirim GET /api/auth/ping. Endpoint ini ringan (tidak menyentuh data) dan menerima kedua jenis kredensial:

curl "${API_URL}/api/auth/ping" \
  -H "Authorization: Bearer ${TOKEN}"
# atau
curl "${API_URL}/api/auth/ping" \
  -H "X-Api-Key: ${API_KEY}"

• HTTP 200 — { "ok": true, "message": "pong" }. Kredensial valid.
• HTTP 401 not-authenticate — Token tidak valid atau kedaluwarsa → lakukan refresh.
• HTTP 401 session-revoked — Sesi sudah di-revoke (logout di tempat lain, take-over, atau deteksi replay) → refresh tidak akan berhasil, login ulang.

Jika Anda juga membutuhkan profil pengguna (role, permissions, email), gunakan GET /api/account/profile — endpoint tersebut memvalidasi kredensial dengan cara yang sama.

Siklus Hidup Token & Sesi

Setiap login membuat satu sesi di server. access_token memuat ID sesi pada claim sid; bila sesi di-revoke, token tersebut ditolak meskipun belum kedaluwarsa. Tiga potongan berikut menggambarkan alur yang harus ditangani klien Bearer token.

1. Sesi yang berjalan normal

Satu sesi berisi banyak access token yang saling menggantikan lewat refresh, sampai batas waktu sesi tercapai:

Setiap refresh mengembalikan pasangan baru (access_token + refresh_token); pasangan lama hangus. Batas sesi tidak bergeser karena refresh.

2. Respons yang harus ditangani klien

3. Apa yang mengakhiri sesi

Admin dapat mengubah durasi lewat environment variable gateway (sintaks durasi Go, mis. 45s, 12h):

Refresh Token

Ketika access_token kedaluwarsa (401 not-authenticate), tukarkan refresh_token dengan pasangan token baru lewat POST /api/auth/refresh. Endpoint ini tidak memerlukan header Authorization.

curl -X POST "${API_URL}/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "'"${REFRESH_TOKEN}"'" }'

{
  "ok": true,
  "message": "Token refreshed",
  "access_token": "eyJ...baru...",
  "refresh_token": "eyJ...baru...",
  "name": "Admin Utama"
}

Aturan yang perlu diperhatikan:

• Rotasi — refresh token lama langsung tidak berlaku; selalu simpan pasangan yang baru dikembalikan.
• Tidak memperpanjang sesi — pasangan baru mewarisi batas waktu sesi semula (1/3/7 hari). Setelah itu, login ulang.
• Deteksi replay — mengirim refresh token yang sudah pernah dirotasi dianggap sebagai token bocor dan merevoke seluruh sesi pengguna tersebut (superadmin: hanya sesi yang bersangkutan). Refresh token yang di-revoke lewat logout/take-over hanya ditolak.
• Single-flight — jika aplikasi Anda menjalankan request paralel, pastikan hanya satu proses refresh berjalan pada satu waktu dan request lain menunggu hasilnya; dua refresh bersamaan dengan token yang sama akan memicu deteksi replay di atas.

Logout

Untuk mengakhiri sesi di server, kirim POST /api/auth/logout dengan refresh_token pada body. Endpoint ini tidak memerlukan header Authorization — dengan begitu logout tetap bisa dilakukan meski access token sudah kedaluwarsa.

curl -X POST "${API_URL}/api/auth/logout" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "'"${REFRESH_TOKEN}"'" }'

Setelah logout, refresh token tersebut dan access token yang terikat pada sesi yang sama ditolak (401 session-revoked). Endpoint ini idempoten — token yang sudah di-revoke, kedaluwarsa, tidak dikenal, atau body kosong tetap dijawab 200.

Integration Lock (X-Integration-Signature)

Route privat /api/* dilindungi integration lock: request yang membawa Authorization: Bearer harus menyertakan header X-Integration-Signature berisi JWT HS256 pendek yang ditandatangani dengan secret per-deployment. Dashboard Lenz melakukannya otomatis. Tujuannya menutup penyalahgunaan API memakai kredensial login pengguna yang "dipinjam" dari browser.

Request Bearer tanpa signature yang valid dijawab HTTP 403:

{ "ok": false, "code": "integration_lock", "message": "integration signature required" }

Untuk memeriksa apakah signature yang Anda pegang masih sinkron (mis. setelah redeploy), gunakan endpoint publik GET /api/auth/status — ia selalu menjawab 200 dengan flag integration: true|false dan tidak pernah membocorkan secret.

Otentikasi WebSocket

Browser tidak bisa mengirim header kustom pada handshake WebSocket, sehingga middleware otentikasi menerima kredensial yang sama melalui query parameter: authorization, x-api-key, dan x-user-permissions. Nilai authorization boleh berupa token mentah maupun berawalan Bearer . Channel WebSocket juga dikecualikan dari integration lock.

const url = new URL(`wss://${BASE_URL}/api/alert_channel`);
url.searchParams.set('x-api-key', API_KEY);
url.searchParams.set('disable_base64_image', 'true');

const ws = new WebSocket(url.toString());
ws.onmessage = (e) => console.log(JSON.parse(e.data));

const url = new URL(`wss://${BASE_URL}/api/alert_channel`);
url.searchParams.set('authorization', accessToken); // tanpa awalan "Bearer " juga diterima
url.searchParams.set('disable_base64_image', 'false');

const ws = new WebSocket(url.toString());

import WebSocket from 'ws';

const ws = new WebSocket(`wss://${BASE_URL}/api/alert_channel`, {
  headers: { 'X-Api-Key': API_KEY },
});

Detail parameter filter dan format payload setiap channel dibahas di Events — WebSocket Protocol.

DPoP (Opsional)

Backend mendukung DPoP (RFC 9449, sender-constrained tokens): access/refresh token diikat ke kunci privat non-extractable di browser, sehingga token yang bocor tidak berguna tanpa proof dari browser asal. Fitur ini dikendalikan admin lewat env DPOP_MODE (off — default, monitor, require) dan hanya memengaruhi jalur Authorization: Bearer. Login via API key dan request federated tidak pernah terikat DPoP.

Header Federation: X-User-Permissions

Dalam arsitektur multi-instance Lenz, ada satu Federation Module (Core) yang berperan sebagai aggregator, dan satu atau lebih remote instance (instance backend tambahan). Saat Federation Module meneruskan request pengguna ke remote instance, ia tidak menggunakan Bearer Token pengguna secara langsung. Sebagai gantinya, Federation Module:

1. Mengautentikasi dirinya ke remote instance menggunakan API key remote instance (X-Api-Key).
2. Mengemas informasi pengguna dan izin yang sudah difilter ke dalam JWT baru.
3. Menandatangani JWT tersebut menggunakan API key remote instance sebagai HMAC secret.
4. Menyertakan JWT tersebut di header X-User-Permissions.

Remote instance kemudian memvalidasi tanda tangan JWT menggunakan API key-nya sendiri, mengekstrak izin pengguna, dan menjalankan access control berbasis data JWT — tanpa perlu lookup role ke database lokalnya.

Struktur Payload JWT X-User-Permissions

{
  "sub": "federer:123",
  "email": "[email protected]",
  "role_id": "operator-role",
  "role_name": "operator-role",
  "permissions": {
    "[remote]core": {
      "site_id|1": ["stream-abc", "stream-def"],
      "site_id|2": ["*"],
      "no_site": ["stream-xyz"]
    }
  },
  "iat": 1705123456,
  "exp": 1705123756
}

Skenario Tanpa API Key Remote Instance (Mode Internal)

Jika Federation Module dijalankan satu cluster dengan remote instance dan tidak ingin pakai API key, secret JWT default PERMISSIONS_JWT_SECRET (env var) digunakan oleh kedua sisi. Mode ini tidak direkomendasikan untuk produksi karena tidak memberi isolasi per instance — bocornya secret di satu tempat berarti seluruh cluster terkompromi.

Pesan Error Umum

Respons error otentikasi selalu menyertakan field code yang bisa dibaca mesin — gunakan code, bukan message, untuk percabangan logika di klien.

Tips Integrasi

Selanjutnya