Autentikasi

API menggunakan API key untuk autentikasi. Semua request ke REST, GraphQL, dan MCP API harus menyertakan API key melalui header Authorization: Bearer.

Mendapatkan API Key

Ikuti langkah-langkah berikut untuk mendapatkan API key Anda:

Daftar — Buat akun gratis di kodepos.dev

Dashboard — Buka halaman dashboard di /app

Buat API Key — Klik tombol buat API key di bagian API Keys

Menggunakan API Key

API key dikirim melalui header Authorization: Bearer di setiap request:

curl -H "Authorization: Bearer kp_live_abc123def456" \
  "https://api.kodepos.dev/kodepos/api/provinces"

Format API Key

API key dikirim melalui header Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx. Semua API key memiliki prefiks kp_live_ diikuti oleh string acak. Contoh: kp_live_abc123def456ghi789.

curl -H "Authorization: Bearer kp_live_abc123def456ghi789" \
  "https://api.kodepos.dev/kodepos/api/provinces"

Maksimal 2 API key aktif per akun. Jika Anda memerlukan lebih banyak, silakan hubungi admin.

Autentikasi MCP Server

MCP Server menggunakan Bearer token yang sama dengan REST dan GraphQL API. Token dikirim melalui header Authorization dalam konfigurasi MCP client:

{
  "mcpServers": {
    "kodepos": {
      "url": "https://api.kodepos.dev/api/kodepos/mcp",
      "headers": {
        "Authorization": "Bearer kp_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Satu API key berlaku untuk semua interface: REST API, GraphQL API, dan MCP Server. Tidak perlu membuat key terpisah untuk setiap interface.

Rotasi API Key

Untuk keamanan, sebaiknya lakukan rotasi API key secara berkala. Proses rotasi dilakukan secara manual:

Buat API key baru — Terlebih dahulu buat API key baru dari dashboard

Perbarui konfigurasi — Ganti API key lama dengan yang baru di seluruh aplikasi Anda

Cabut API key lama — Setelah memastikan semua layanan menggunakan key baru, cabut (revoke) key lama dari dashboard

Mencabut API key akan langsung membatalkan akses. Pastikan semua layanan sudah menggunakan key baru sebelum mencabut key lama.

Error Autentikasi

Jika autentikasi gagal, API akan mengembalikan response dengan HTTP status 401 dan error code yang sesuai:

HTTP Status	Error Code	Deskripsi
401	AUTHENTICATION_REQUIRED	Header Authorization: Bearer tidak disertakan dalam request
401	INVALID_API_KEY	API key tidak valid atau sudah dicabut

Header otorisasi tidak disertakan

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "API key is required. Include Authorization: Bearer header."
  }
}

API key tidak valid

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Login via Email OTP

Website Kode Pos API menggunakan sistem autentikasi Email OTP tanpa password. Proses login sebagai berikut:

Masukkan email — Kunjungi halaman login dan masukkan alamat email Anda

Terima OTP — Kode OTP (one-time password) akan dikirim ke email Anda

Verifikasi — Masukkan kode OTP untuk verifikasi, sesi (session) akan dibuat secara otomatis