Autentikasi dan API key

Setiap request ke Se-Hari API dikenali lewat API key yang dikirim di header Authorization. Tidak ada OAuth, tidak ada session cookie, tidak ada tanda tangan request. Satu header, dan itu saja.

curl "https://se-hari.com/api/v1/me" \
  -H "Authorization: Bearer sh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

#Bentuk key

Key selalu berbentuk sh_live_ diikuti 43 karakter base64url — total 51 karakter, selalu. Panjangnya tetap, jadi mengukurnya adalah cara tercepat memastikan key tersalin utuh:

echo -n "$SEHARI_API_KEY" | wc -c
# 51  ← benar
# 43  ← terpotong saat disalin

Kami menyimpan key sebagai hash, bukan sebagai teks. Konsekuensinya: key hanya ditampilkan satu kali, saat dibuat. Tidak ada tombol "lihat lagi" karena kami sendiri tidak bisa melihatnya. Kalau hilang, cabut key itu dan buat yang baru.

Tidak ada prefix sh_test_. Se-Hari belum punya environment terpisah, dan key uji yang ternyata berdampak nyata jauh lebih berbahaya daripada tidak punya key uji sama sekali.

#Scope

Scope menentukan apa yang boleh dilakukan sebuah key. Ada delapan:

Scope tidak bisa ditambahkan ke key yang sudah ada. Ini keputusan yang disengaja, bukan keterbatasan: scope yang bisa dinaikkan diam-diam berarti key yang bocor hari ini bisa menjadi lebih berbahaya besok. Kalau sebuah key kurang izin, buat key baru, ganti di konfigurasi, lalu cabut yang lama.

Beri setiap integrasi key sendiri. Manfaatnya baru terasa saat ada masalah: key yang dicabut hanya mematikan satu integrasi, log aktivitas menunjukkan integrasi mana yang melakukan apa, dan batas kredit harian bisa disesuaikan per integrasi. Key bersama yang dipakai lima sistem mengubah setiap pencabutan menjadi insiden.

#Batas kredit harian

Setiap key bisa diberi batas kredit harian di dashboard. Ini pengaman termurah yang tersedia: kalau key bocor atau sebuah perulangan salah tulis, kerugian berhenti di angka yang Anda tentukan.

Saat batas tercapai, operasi yang memakai kredit dijawab 403 credit_cap_exceeded — sementara operasi baca tetap berjalan normal. Batas dihitung ulang setiap hari.

Perhatikan bedanya dengan insufficient_credits: kode itu berarti saldo akun Anda memang habis, sedangkan yang ini berarti saldo masih ada tapi key-nya sudah menyentuh jatah hariannya.

#Masa berlaku dan pencabutan

Key bisa diberi tanggal kedaluwarsa saat dibuat: 30, 90, 365 hari, atau tanpa batas. Untuk integrasi jangka panjang, tanpa batas ditambah rotasi berkala lebih praktis daripada kedaluwarsa otomatis yang mematikan produksi di tengah malam.

Pencabutan berlaku seketika. Request berikutnya dengan key itu dijawab 401, tanpa jeda propagasi.

#Kalau key bocor

Urutannya penting:

1. Cabut key-nya sekarang di dashboard. Ini menghentikan pendarahan; langkah berikutnya bisa menunggu.
2. Buka tab Aktivitas dan lihat apa yang sempat dilakukan key itu.
3. Periksa riwayat pemakaian kredit lewat GET /credits/usage untuk tahu berapa yang terpakai.
4. Buat key baru dan perbarui konfigurasi integrasi Anda.

Batas kredit harian yang sudah terpasang sejak awal membuat langkah 3 jauh lebih menyenangkan dibaca.

#Kesalahan yang paling sering

Tiga kode error yang sering tertukar, padahal tindakannya berbeda:

• missing_authorization (401) — header Authorization tidak sampai sama sekali. Hampir selalu berarti variabel lingkungan kosong.
• invalid_api_key (401) — header ada, key-nya ditolak. Salah, dicabut, atau kedaluwarsa; ketiganya dijawab sama supaya tidak memberi petunjuk kepada penebak.
• insufficient_scope (403) — key sah dan dikenali, tapi tidak punya izin untuk operasi itu. 403 justru membuktikan kredensial Anda benar.

#Menyimpan key dengan aman

Jangan pernah menaruh API key di dalam kode atau di repositori. Selain alasan keamanan yang sudah jelas, variabel lingkungan membuat kegagalan terlihat lebih awal: proses yang gagal start karena variabelnya kosong jauh lebih mudah didiagnosis daripada proses yang berjalan normal sambil mengirim header kosong ke setiap request.

// Periksa saat aplikasi mulai, bukan saat request pertama.
const KEY = process.env.SEHARI_API_KEY;
if (!KEY?.startsWith('sh_live_')) {
	throw new Error('SEHARI_API_KEY belum diisi atau bentuknya tidak benar');
}

#Selanjutnya

• Mulai cepat — request pertama
• Rate limit — batas frekuensi dan cara membacanya
• Kredit — cara penagihan bekerja