Dokumentasi API

📚 Dokumentasi API SSO BPS

🖥️ Environment Configuration

SSO BPS menggunakan mekanisme redirect untuk autentikasi. Setelah berhasil login, pengguna akan diarahkan kembali ke aplikasi dengan membawa authorization code.

Base URL (OAuth): https://sso.bps9702.com/sso/
Base URL (Data API): https://sso.bps9702.com/api/

🔐 OAuth Endpoints

Endpoint untuk proses autentikasi SSO

1. 🚪 Authorize

GET sso.bps9702.com/sso/authorize

📥 Parameters:

client_id (required) - ID aplikasi client
state (optional) - State parameter untuk keamanan

📤 Response: Redirect ke callback URL dengan authorization code

2. 🔑 Token

POST sso.bps9702.com/sso/token

📥 Body Parameters:

code (required) - Authorization code dari step authorize
client_id (required) - ID aplikasi client
client_secret (required) - Secret aplikasi client

📤 Response:

{
  "status": "success",
  "data": {
    "user_id": "123456789",
    "name": "John Doe",
    "nip_9": "123456789",
    "nip_18": "199001011234567890",
    "email": "john@example.com",
    "roles": ["admin", "user"]
  }
}

3. ✅ Check

POST sso.bps9702.com/sso/check

📥 Body Parameters:

code (required) - Authorization code untuk dicek

📤 Response: Data user seperti endpoint token

📊 Data Endpoints

Endpoint untuk mengambil data pegawai dan role (hanya user aktif)

⚠️ Penting: Semua endpoint ini hanya mengembalikan user dengan status is_active = true

1. 👥 Get All Employees

POST sso.bps9702.com/api/employees

📖 Deskripsi: Mengambil data semua pegawai dengan status aktif

🔒 Keamanan: Memerlukan client_secret dari aplikasi yang terdaftar

📥 Body Parameters:

client_secret (required) - Client secret dari aplikasi yang terdaftar

🧪 Test cURL:

curl -X POST "sso.bps9702.com/api/employees" \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -H "Accept: application/json" \

  -d "client_secret=your_client_secret"

📤 Response:

{
  "status": "success",
  "message": "Data pegawai berhasil diambil",
  "data": [
    {
      "nip_9": "123456789",
      "nip_18": "199001011234567890", 
      "name": "John Doe",
      "email": "john@example.com",
      "roles": ["admin", "user"]
    }
  ],
  "total": 50,
  "requested_by": "Nama Aplikasi"
}

2. 🛡️ Get All Roles

GET sso.bps9702.com/api/roles

📖 Deskripsi: Mengambil data semua role dengan informasi lengkap dan jumlah user aktif

🧪 Test URL:

curl -X GET "sso.bps9702.com/api/roles" -H "Accept: application/json"

📤 Response:

{
  "status": "success",
  "message": "Data role berhasil diambil",
  "data": [
    {
      "name": "admin",
      "description": "Administrator sistem",
      "user_count": 5
    },
    {
      "name": "user", 
      "description": "User biasa",
      "user_count": 45
    },
    {
      "name": "umum",
      "description": "User umum",
      "user_count": 20
    }
  ],
  "total": 3
}

3. 📝 Get Role Names

GET sso.bps9702.com/api/role-names

📖 Deskripsi: Mengambil daftar nama role saja (list sederhana untuk dropdown/select)

🧪 Test URL:

curl -X GET "sso.bps9702.com/api/role-names" -H "Accept: application/json"

📤 Response:

{
  "status": "success",
  "message": "Daftar nama role berhasil diambil",
  "data": ["admin", "user", "umum"],
  "total": 3
}

4. 👥🛡️ Get Employees by Role

POST sso.bps9702.com/api/employees/by-role

📖 Deskripsi: Mengambil data pegawai yang memiliki role tertentu

🔒 Keamanan: Memerlukan client_secret dari aplikasi yang terdaftar

📥 Body Parameters:

client_secret (required) - Client secret dari aplikasi yang terdaftar
role (required) - Nama role yang dicari (case insensitive)

🧪 Test cURL:

curl -X POST "sso.bps9702.com/api/employees/by-role" \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -H "Accept: application/json" \

  -d "client_secret=your_client_secret&role=admin"

curl -X POST "sso.bps9702.com/api/employees/by-role" \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -H "Accept: application/json" \

  -d "client_secret=your_client_secret&role=user"

📤 Success Response:

{
  "status": "success",
  "message": "Data pegawai dengan role 'admin' berhasil diambil",
  "data": [
    {
      "nip_9": "123456789",
      "nip_18": "199001011234567890",
      "name": "John Doe",
      "email": "john@example.com", 
      "roles": ["admin", "user"]
    },
    {
      "nip_9": "111222333",
      "nip_18": "199203151112223334",
      "name": "Admin User",
      "email": "admin@example.com",
      "roles": ["admin"]
    }
  ],
  "role_info": {
    "name": "admin",
    "description": "Administrator sistem"
  },
  "total": 2,
  "requested_by": "Nama Aplikasi"
}

❌ Error Responses

🔒 Missing Client Secret (400):

{
  "status": "error",
  "message": "Client secret diperlukan",
  "errors": {
    "client_secret": ["The client secret field is required."]
  },
  "error_code": "MISSING_CLIENT_SECRET"
}

🚫 Invalid Client Secret (401):

{
  "status": "error",
  "message": "Client secret tidak valid atau aplikasi tidak aktif",
  "error_code": "INVALID_CLIENT_SECRET"
}

🔍 Role Not Found (404):

{
  "status": "error",
  "message": "Role tidak ditemukan",
  "error_code": "ROLE_NOT_FOUND"
}

⚠️ Invalid Request (400):

{
  "status": "error",
  "message": "Parameter tidak valid",
  "errors": {
    "role": ["The role field is required."]
  },
  "error_code": "INVALID_REQUEST"
}

💥 Internal Server Error (500):

{
  "status": "error",
  "message": "Terjadi kesalahan internal server",
  "error_code": "INTERNAL_SERVER_ERROR"
}

💡 Usage Examples

📱 JavaScript/Fetch (Protected Endpoints):

// Get all employees (POST with client_secret)
const response = await fetch('/api/employees', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Accept': 'application/json'
  },
  body: 'client_secret=your_client_secret'
});
const data = await response.json();

// Get employees by role (POST with client_secret)
const admins = await fetch('/api/employees/by-role', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Accept': 'application/json'
  },
  body: 'client_secret=your_client_secret&role=admin'
});
const adminData = await admins.json();

📱 JavaScript/Fetch (Public Endpoints):

// Get all roles (GET, no client_secret needed)
const roles = await fetch('/api/roles');
const roleData = await roles.json();

// Get role names (GET, no client_secret needed)
const roleNames = await fetch('/api/role-names');
const nameData = await roleNames.json();

🐘 PHP/cURL (Protected Endpoints):

// Get all employees
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'sso.bps9702.com/api/employees',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => 'client_secret=your_client_secret',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Accept: application/json']
]);
$response = curl_exec($curl);
$data = json_decode($response, true);

🐘 PHP/cURL (Public Endpoints):

// Get all roles (no client_secret needed)
$response = file_get_contents('sso.bps9702.com/api/roles');
$data = json_decode($response, true);

🤖 AI-Friendly Documentation: Memerlukan dokumentasi dalam format JSON untuk AI/automation tools? Akses dokumentasi API kami yang comprehensive di:
sso.bps9702.com/api/documentation
Endpoint publik yang berisi spesifikasi lengkap API, OAuth flow, error codes, dan contoh penggunaan dalam format JSON.

Tentang SSO BPS

🔐 Single Sign-On (SSO)

Sistem autentikasi terpusat untuk semua aplikasi internal BPS Jayawijaya. Dengan satu kali login, user dapat mengakses berbagai aplikasi tanpa perlu login berulang kali.

👥 Untuk Developer:

Integrasikan aplikasi Anda dengan SSO
Gunakan OAuth 2.0 flow untuk autentikasi
Akses data pegawai dan role melalui API

🚀 Cara Memulai:

Hubungi admin untuk mendapatkan akun
Login dengan akun yang diberikan
Daftarkan aplikasi Anda (client app)
Dapatkan Client ID & Secret
Implementasikan OAuth flow di aplikasi
Test integrasi dengan endpoint yang tersedia

📞 Butuh Bantuan?

Hubungi tim IT BPS Jayawijaya untuk bantuan teknis dan registrasi akun developer.

🚨 Important Notes

Semua Data Endpoints mengembalikan hanya user aktif (is_active = true)
Protected Endpoints (POST): /employees dan /employees/by-role memerlukan client_secret
Public Endpoints (GET): /roles dan /role-names dapat diakses tanpa client_secret
OAuth endpoints menggunakan path /sso/
Data endpoints menggunakan path /api/
Semua response menggunakan format JSON yang konsisten
Parameter role pada endpoint employees/by-role bersifat case-insensitive
Client Secret harus dari aplikasi yang terdaftar dan aktif