Autentikasi & API Key

Pelajari cara login dengan Email OTP, mendapatkan API key, menggunakannya via header Authorization: Bearer, serta mengelola siklus hidup key (rotasi dan pencabutan). Berlaku untuk REST, GraphQL, dan MCP API.

Mendapatkan API Key

Ikuti langkah-langkah berikut untuk mendapatkan API key Anda:

Daftar — Buat akun gratis di www.kodepos.dev

Lengkapi profil — Buka /app/akun dan isi display name. Nama ini wajib diisi sebelum Anda dapat membuat API key.

Buka halaman API Key — Navigasi ke /app/api-key dan klik tombol "Buat API Key".

Salin API Key — Key hanya ditampilkan sekali setelah dibuat. Segera salin dan simpan di tempat aman.

Setiap akun dapat memiliki maksimal 2 API key aktif secara bersamaan. Semua key dalam satu akun berbagi pool kredit yang sama. Bila perlu membuat key baru dan sudah mencapai batas ini, cabut salah satu key terlebih dahulu (lihat bagian Rotasi & Pencabutan di bawah).

API key hanya ditampilkan sekali saat dibuat. Jika Anda lupa atau kehilangan key, Anda harus membuat key baru dan mencabut key yang hilang.

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"

Autentikasi MCP Server

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

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

Konfigurasi lengkap per platform (n8n, OpenClaw, Claude Desktop, Cursor, VS Code) tersedia di dokumentasi MCP Server

Lihat Dokumentasi MCP Server

Mencabut API Key

Anda dapat mencabut (revoke) API key kapan saja dari dashboard. Setelah dicabut, key tersebut tidak dapat digunakan lagi untuk mengakses API.

Buka /app/api-key — Lihat daftar API key aktif Anda

Klik "Revoke" pada key yang ingin dicabut — Konfirmasi pencabutan key

Berlaku segera — Key dicabut seketika tanpa masa tenggang (grace period)

Pencabutan API key berlaku seketika. Semua request yang menggunakan key yang dicabut akan langsung ditolak dengan error 401 Unauthorized. Pastikan tidak ada layanan yang masih menggunakan key tersebut.

Rotasi API Key

Untuk keamanan, sebaiknya lakukan rotasi API key secara berkala (misalnya setiap 3-6 bulan) atau segera bila Anda mencurigai key telah bocor. Karena setiap akun dibatasi maksimal 2 API key aktif, rotasi dilakukan dengan urutan berikut untuk menghindari downtime:

Buat API key baru — Pastikan Anda masih memiliki slot key tersedia (maksimal 2 per akun)

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

Uji koneksi — Pastikan semua layanan berfungsi dengan key baru

Cabut API key lama — Setelah yakin semua layanan sudah migrasi, cabut key lama (lihat langkah di atas)

Praktik Terbaik

Untuk keamanan optimal, ikuti praktik terbaik berikut dalam mengelola API key:

Gunakan Environment Variables

Jangan hardcode API key dalam source code. Gunakan environment variables untuk menyimpan key dengan aman:

KODEPOS_API_KEY=your_api_key_here

Jangan Commit API Key

Pastikan API key tidak masuk ke version control. Tambahkan file environment (seperti .env) ke .gitignore.

Rotasi Berkala

Lakukan rotasi API key secara berkala (misalnya setiap 3-6 bulan) untuk mengurangi risiko jika key bocor. Ikuti praktik rotasi aman: buat key baru → migrasi → cabut key lama.

Key Terpisah per Lingkungan

Jika memungkinkan, gunakan API key berbeda untuk development, staging, dan production. Namun karena batas maksimal 2 key per akun, Anda bisa menggunakan 1 key untuk development dan 1 key untuk production.

Monitor Penggunaan

Pantau penggunaan API secara berkala melalui dashboard. Jika menemukan aktivitas mencurigakan atau penggunaan tidak biasa, segera cabut API key dan buat yang baru.

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