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.

Halaman ini mencakup seluruh alur otentikasi secara teknis — dari cara mendapatkan token, cara menyertakannya di setiap request, hingga alur federation antar-instance backend.

Tipe Otentikasi

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": "admin@example.com",
    "password": "your-password"
  }'

const res = await fetch(`${API_URL}/api/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    user_access: "admin@example.com",
    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": "admin@example.com", "password": "your-password"},
    timeout=10,
)
data = res.json()
access_token = data["access_token"]

{
  "ok": true,
  "message": "success",
  "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. Gunakan access_token yang dikembalikan dengan cara yang sama — header Authorization: Bearer <token>.

Verifikasi Token

Untuk memastikan token masih berlaku, kirim GET /api/account/profile. Endpoint ini juga mengembalikan profil lengkap pengguna aktif.

curl "${API_URL}/api/account/profile" \
  -H "Authorization: Bearer ${TOKEN}"

• HTTP 200 — Token valid. Body berisi data profil pengguna.
• HTTP 401 — Token tidak valid atau kedaluwarsa. Pengguna perlu login ulang.

Refresh Token

Backend API mengembalikan refresh_token saat login. Saat ini tidak ada endpoint khusus untuk menukar refresh token menjadi access token baru — lapangan tersebut diisi untuk kompatibilitas masa depan dan disimpan klien.

Jika access_token tidak lagi valid (respons 401), pengguna atau layanan harus login ulang menggunakan kredensial atau API key.

Logout

Untuk merevoke token dan mengakhiri sesi, kirim POST /api/auth/logout dengan token aktif di header:

curl -X POST "${API_URL}/api/auth/logout" \
  -H "Authorization: Bearer ${TOKEN}"

Setelah logout berhasil, token tidak bisa dipakai lagi untuk request berikutnya. Klien Lenz menambahkan ini ke alur logout otomatis (idle timeout, absolute timeout, dan tombol Logout di dashboard).

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": "federrer:123",
  "email": "user@example.com",
  "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

Tips Integrasi

Selanjutnya