Otentikasi

Panduan JWT, API key, dan header federation untuk integrasi dengan Raisa Gateway.

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.

Jika Anda hanya operator yang memakai dashboard Lenz, baca Memulai. Halaman ini lebih dalam dan ditujukan untuk integrator yang memanggil API langsung dari aplikasi atau skrip mereka.

Tipe Otentikasi

Tipe	Header yang Dipakai	Use Case
Bearer Token (JWT)	`Authorization: Bearer <jwt>`	Login sesi pengguna
API Key	`X-Api-Key: <key>`	Service-to-service / automasi / CI-CD
Federated	`X-Api-Key: <remote_key>` + `X-User-Permissions: <jwt>`	Federer → Remote (multi-instance)

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.

Kirim kredensial ke `/api/auth/token`

Gunakan field user_access untuk username atau alamat email, dan password untuk kata sandi.

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

Terima respons berisi token

Jika kredensial valid, server mengembalikan objek JSON berikut:

Respons login berhasil

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

Simpan nilai access_token — Anda akan membutuhkannya di setiap request berikutnya.

Field name berisi nama tampilan pengguna. Untuk mendapatkan detail profil lengkap (role, permissions, email), gunakan endpoint GET /api/account/profile setelah login.

Sertakan `access_token` di setiap request

Kirimkan token di header Authorization dengan format Bearer <token>:

Request dengan Bearer Token

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

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

Jangan pernah menyimpan API key secara langsung di source code atau commit ke repository publik. Simpan di environment variable, secret manager (seperti Vault atau AWS Secrets Manager), atau file .env yang masuk ke dalam .gitignore.

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.

Verifikasi token 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.

Token tidak memiliki durasi kedaluwarsa berbasis waktu yang kaku. Sesi pengguna berakhir karena idle timeout (dikonfigurasi oleh admin) atau karena logout eksplisit. Jika Anda menerima 401 pada request normal, lakukan login ulang untuk mendapatkan token baru.

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:

Mengautentikasi dirinya ke Remote menggunakan API key Remote (X-Api-Key).
Mengemas informasi pengguna dan izin yang sudah difilter ke dalam sebuah JWT baru.
Menandatangani JWT tersebut menggunakan API key Remote sebagai HMAC secret.
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`

Payload JWT X-User-Permissions

{
  "sub": "federrer: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
}

Field	Deskripsi
`sub`	Subject identifier dalam format `"federrer:{user_id}"`
`email`	Alamat email pengguna
`role_id` / `role_name`	Nama role (bukan ID database)
`permissions`	Izin pengguna yang sudah difilter untuk Remote target, dengan key diubah menjadi `[remote]core`
`iat` / `exp`	Timestamp issued-at dan expiration (TTL 5 menit)

Header X-User-Permissions hanya boleh dikirim oleh Federer yang sudah terdaftar dan memiliki API key Remote yang valid. Jangan gunakan header ini untuk integrasi pihak ketiga — request semacam itu akan ditolak karena JWT tidak akan bisa divalidasi tanpa API key yang tepat.

Logout

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

Logout dan revoke token

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:

Parameter	Lokasi	Tipe	Wajib	Deskripsi
`user_access`	Body (JSON)	string	Ya	Username atau alamat email
`password`	Body (JSON)	string	Ya	Kata sandi

Login dengan API key:

Header	Tipe	Wajib	Deskripsi
`X-Api-Key`	string	Ya	API key yang valid

Respons berhasil (HTTP 200):

Respons POST /api/auth/token

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

Field	Tipe	Deskripsi
`ok`	boolean	`true` jika login berhasil
`message`	string	Pesan status
`access_token`	string	JWT untuk digunakan di header `Authorization: Bearer`
`refresh_token`	string	Token untuk keperluan refresh (saat ini disimpan di client)
`name`	string	Nama tampilan pengguna

Error:

HTTP Status	Kondisi
`401`	Kredensial tidak valid atau API key tidak ditemukan

`POST /api/auth/logout`

Merevoke token aktif dan mengakhiri sesi pengguna.

Header	Tipe	Wajib	Deskripsi
`Authorization`	string	Ya	`Bearer <access_token>`

Respons berhasil (HTTP 200):

Respons POST /api/auth/logout

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

`GET /api/account/profile`

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

Header	Tipe	Wajib	Deskripsi
`Authorization`	string	Ya	`Bearer <access_token>`

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

Error:

HTTP Status	Kondisi
`401`	Token tidak valid atau sudah kedaluwarsa

Struktur respons detail dari /api/account/profile dapat bervariasi tergantung konfigurasi role dan permissions. Untuk melihat struktur aktual di lingkungan Anda, gunakan tab Network di DevTools browser saat membuka dashboard Lenz.

Tips Integrasi

Best practice untuk integrator:

Simpan access_token di memori aplikasi atau secure storage — hindari menyimpan di localStorage yang dapat diakses JavaScript publik jika memungkinkan.
Implementasikan handler untuk respons 401: tangkap error ini dan arahkan pengguna ke alur login ulang secara otomatis.
Untuk integrasi service-to-service, gunakan API key dan rotasi secara berkala sesuai kebijakan keamanan organisasi Anda.
Untuk federated requests, perhatikan TTL JWT X-User-Permissions yang hanya 5 menit — Federer akan membuat JWT baru untuk setiap batch request.
Jangan hardcode token atau API key di kode sumber. Gunakan environment variable atau secret manager.

Otentikasi

Pengenalan

Tipe Otentikasi

Kirim kredensial ke `/api/auth/token`

Terima respons berisi token

Sertakan `access_token` di setiap request

Verifikasi Token

Refresh Token

Header Federation: `X-User-Permissions`

Struktur Payload JWT `X-User-Permissions`

Logout

Pesan Error Umum

API Reference

`POST /api/auth/token`

`POST /api/auth/logout`

`GET /api/account/profile`

Tips Integrasi

Selanjutnya

Konsep Dasar

API Key

Remotes (Federation)

On this page

Otentikasi

401 Unauthorized — Authorization not found

401 Unauthorized — Failed verify token

401 Unauthorized — Sesi berakhir / Token expired

403 Forbidden — not allowed for access this resource

401 Unauthorized — Failed to validate API key

Konsep Dasar

API Key

Remotes (Federation)

On this page