Otentikasi

Pengenalan

Raisa Gateway 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 satu dari keduanya. Untuk arsitektur multi-instance (federation), terdapat mekanisme tambahan berupa header X-User-Permissions yang memungkinkan Federer meneruskan konteks izin pengguna ke Remote secara aman.

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

Tipe Otentikasi

Login Cepat (Untuk Operator)

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

Login dengan Username & Password

curl -X POST "${RAISA_API_URL}/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "user_access": "admin@example.com",
    "password": "your-password"
  }'

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

curl "${RAISA_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 yang tidak memiliki konteks pengguna interaktif. API key dibuat oleh admin melalui menu Configuration → API Key di dashboard Lenz.

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

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

Server akan mengembalikan respons dalam format yang sama dengan login username/password. Gunakan access_token yang dikembalikan untuk request selanjutnya dengan cara yang sama — header Authorization: Bearer <token>.

Verifikasi Token

Untuk memastikan apakah token yang Anda miliki masih berlaku, kirim request GET /api/account/profile. Endpoint ini juga mengembalikan data profil pengguna yang sedang aktif.

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

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

Refresh Token

Raisa Gateway mengembalikan refresh_token saat login, namun saat ini tidak tersedia endpoint khusus untuk menukar refresh token menjadi access token baru. Jika access_token tidak lagi valid (respons 401), pengguna atau layanan harus melakukan login ulang menggunakan kredensial atau API key.

Header Federation: X-User-Permissions

Dalam arsitektur multi-instance Lenz, terdapat satu node Federer (Core) yang berperan sebagai aggregator, dan satu atau lebih node Remote (instance Raisa Gateway tambahan). Ketika Federer meneruskan request pengguna ke sebuah Remote, ia tidak menggunakan Bearer Token pengguna secara langsung. Sebagai gantinya, Federer:

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

Remote kemudian memvalidasi tanda tangan JWT menggunakan API key-nya sendiri, mengekstrak izin pengguna, dan menjalankan access control berbasis data JWT — tanpa perlu melakukan 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
}

Logout

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

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

Setelah logout berhasil, token tidak bisa digunakan lagi untuk request berikutnya.

Pesan Error Umum

API Reference

POST /api/auth/token

Mengotentikasi pengguna dan mengembalikan token akses.

Login dengan username/password:

Login dengan API key:

Respons berhasil (HTTP 200):

{
  "ok": true,
  "message": "success",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "name": "Nama Pengguna"
}

Error:

POST /api/auth/logout

Merevoke token aktif dan mengakhiri sesi pengguna.

Respons berhasil (HTTP 200):

{
  "success": true,
  "message": "logout successful"
}

GET /api/account/profile

Mengembalikan profil pengguna yang sedang aktif. Digunakan juga untuk memverifikasi apakah token masih valid.

Respons berhasil (HTTP 200): Data profil pengguna lengkap termasuk role dan permissions.

Error:

Tips Integrasi

Selanjutnya