CORS (Domain Whitelist)

Kelola domain mana yang boleh memanggil Kode Pos API dari browser menggunakan API key Anda. Pelajari format origin yang valid dan cara kerja CORS header kondisional.

Apa itu CORS Whitelist?

Kebijakan per-akun yang membatasi domain mana yang boleh memanggil Kode Pos API dari browser menggunakan API key Anda.

Secara default, browser membatasi script di halaman Anda untuk membaca respons dari domain lain (kebijakan same-origin). Untuk mengizinkan script tersebut memanggil Kode Pos API, server kami mengirim header Access-Control-Allow-Origin. Fitur CORS Whitelist memungkinkan Anda mengontrol origin mana saja yang menerima header tersebut — sehingga hanya situs yang Anda daftarkan yang dapat memanggil API dari browser menggunakan API key Anda.

Default: tidak ada CORS header yang dikirim: bila Anda belum menambahkan domain apa pun ke whitelist, server tidak akan melampirkan header Access-Control-Allow-Origin pada respons untuk permintaan browser mana pun. Browser kemudian memblokir respons secara native (sesuai spesifikasi CORS) sehingga script di domain lain tidak dapat membacanya. Server tidak mengembalikan error 403 — pemblokiran terjadi di sisi browser.

Server-to-server calls tidak terpengaruh: permintaan dari curl, Node.js (server-side), Python requests, PHP Guzzle, Postman, dan klien non-browser lainnya tidak mengirim header Origin sehingga tidak pernah diblokir oleh fitur ini. Fitur ini hanya berlaku untuk permintaan dari browser.

Endpoint yang Menerapkan Filter CORS

CORS whitelist diterapkan pada endpoint data Kode Pos API yang memerlukan API key — termasuk REST dan GraphQL. Server-to-server calls tidak terpengaruh.

Method	Endpoint	Deskripsi
GET	/kodepos/api/provinces	Daftar provinsi (REST)
GET	/kodepos/api/cities	Daftar kota/kabupaten (REST)
GET	/kodepos/api/districts	Daftar kecamatan (REST)
GET	/kodepos/api/subdistricts	Daftar kelurahan/desa (REST)
GET	/kodepos/api/search	Pencarian kode pos (REST)
POST	/kodepos/graphql	Query & mutation (GraphQL)

Tidak terpengaruh: server-to-server calls (curl, Node, Python, PHP, Postman, dsb.) tidak mengirim header Origin sehingga tidak pernah diblokir oleh fitur ini. CORS hanya berlaku untuk permintaan dari browser.

MCP Server: MCP Server saat ini tidak dikenakan filter whitelist per-akun. Klien MCP (Claude, Cursor, n8n, dsb.) tetap dapat memanggil MCP Server tanpa perlu mendaftarkan origin di whitelist CORS, karena koneksi MCP bersifat server-to-server dan tidak mengirim header Origin seperti browser.

Format Origin

Origin harus berbentuk scheme://host[:port]. Pencocokan bersifat exact (case-insensitive pada host) — wildcard dan path tidak didukung.

Format: scheme://host[:port] — scheme harus http atau https, host di-lowercase, port opsional.

Tidak boleh mengandung path, query, atau fragment — https://example.com/v1 atau https://example.com?x=1 akan ditolak.

Wildcard tidak didukung — https://*.example.com akan ditolak. Setiap subdomain harus didaftarkan secara terpisah sebagai origin masing-masing.

Origin	Status	Catatan
https://api.example.com	Valid	Bentuk kanonik — scheme + host
https://api.example.com:8080	Valid	Port non-default dipertahankan
https://api.example.com/	Valid	Trailing slash otomatis dihapus saat disimpan
http://localhost:3000	Valid	Lingkungan pengembangan lokal
https://api.example.com/v1	Tidak valid	Path tidak diizinkan
https://api.example.com?token=1	Tidak valid	Query string tidak diizinkan
ftp://example.com	Tidak valid	Scheme harus http atau https
api.example.com	Tidak valid	Scheme wajib disertakan
https://*.example.com	Tidak valid	Wildcard tidak didukung — exact match only

Mengelola Whitelist dari Dashboard

Kelola daftar domain whitelist Anda dari halaman CORS di dashboard. Maksimum 10 origin per akun.

Masuk — Gunakan Email OTP untuk login ke dashboard

Lengkapi profil — Buka /app/akun

Buka halaman CORS — Navigasi ke /app/cors dari sidebar dashboard

Tambah domain — Klik tombol "Tambah Domain" dan masukkan origin Anda (contoh: https://api.example.com)

Hapus bila perlu — Setiap origin dapat dihapus satu per satu, atau semua sekaligus menggunakan tombol "Hapus Semua Domain"

Perubahan whitelist berlaku segera ( Redis cache invalidated saat Anda menambah atau menghapus origin). Tidak perlu menunggu refresh atau deploy ulang.

Contoh: Memanggil API dari Browser

Contoh kode untuk memanggil Kode Pos API dari browser. Browser otomatis mengirim header Origin — Anda tidak perlu menyetelnya secara manual. Untuk testing manual dari terminal, sertakan header Origin pada curl.

# Selalu sertakan header Authorization dengan API key Anda.
# Untuk testing dari browser saja, sertakan header Origin.

curl -X GET 'https://api.kodepos.dev/kodepos/api/provinces' \
  -H 'Authorization: Bearer kp_live_xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Origin: https://api.example.com'

Ganti kp_live_xxxxxxxxxxxxxxxxxxxxxxxx dengan API key Anda. Jangan menyimpan API key di kode frontend yang dapat diakses publik — pertimbangkan proxy melalui backend Anda sendiri untuk produksi.

Praktik Terbaik

Untuk konfigurasi whitelist dan debugging CORS error, ikuti praktik terbaik berikut:

1. Daftarkan Semua Environment

Tambahkan origin untuk production, staging, dan http://localhost:3000 untuk pengembangan lokal. Maksimum 10 origin per akun sudah mencakup skenario ini — tidak perlu menghapus origin dev saat rilis ke produksi.

2. Subdomain Adalah Origin Terpisah

https://app.example.com dan https://www.example.com adalah origin yang berbeda dan harus didaftarkan masing-masing. Tidak ada wildcard support — setiap subdomain adalah satu baris di whitelist.

3. Jangan Sebut API Key di Frontend Publik

Walaupun whitelist membatasi origin, API key tetap terlihat di network tab browser. Untuk produksi, pertimbangkan mem-proxy panggilan melalui backend Anda sendiri sehingga API key tidak pernah diekspos ke klien.

4. Debugging CORS Error di Browser

Buka Network tab di browser dev tools, klik request yang gagal, dan periksa apakah header Access-Control-Allow-Origin ada di response. Jika tidak ada, origin browser Anda belum didaftarkan di whitelist — tambahkan dari halaman /app/cors di dashboard. Browser akan menampilkan pesan generic seperti "Access to fetch at ... has been blocked by CORS policy"tanpa menyertakan body respons; ini adalah perilaku native browser sesuai spesifikasi CORS, bukan error dari server.

5. Pastikan Scheme yang Benar

http://example.com dan https://example.com adalah origin yang berbeda. Daftarkan sesuai scheme yang digunakan browser (umumnya https untuk produksi).

Menghapus semua origin dari whitelist akan mengembalikan akun ke keadaan default: server tidak lagi melampirkan header CORS untuk permintaan browser mana pun, sehingga browser memblokir respons secara native sampai Anda menambahkan origin baru. Pastikan tidak ada produksi yang aktif di browser saat melakukan clear-all.