Kontrol perusahaan dan kepercayaan30 Juli 2026Flatkey Team

Praktik Terbaik Pengelolaan Kunci API untuk Produk AI (Daftar Periksa 2026)

Daftar periksa praktis pengelolaan kunci API untuk produk AI: simpan kunci di server, gunakan kunci terpisah per lingkungan, rotasi tanpa waktu henti, verifikasi pencabutan, pindai kebocoran, dan segera tangani kunci yang terekspos.

Praktik Terbaik Pengelolaan Kunci API untuk Produk AI (Daftar Periksa 2026)

Praktik terbaik pengelolaan kunci API mencakup lima hal: simpan kunci di server dan di luar kode, berikan kunci tersendiri dengan cakupan terbatas untuk setiap lingkungan dan beban kerja, simpan kunci di pengelola rahasia, lakukan rotasi dan pencabutan sesuai jadwal yang telah diuji, serta pantau penggunaan tanpa pernah mencatat kunci itu sendiri ke log. Untuk produk AI, risikonya lebih besar daripada kebanyakan API karena kunci model yang bocor dapat menimbulkan tagihan besar dalam hitungan jam sekaligus memberikan akses ke prompt, file, dan pemanggilan alat.

Panduan ini merangkum prinsip-prinsip tersebut menjadi daftar periksa yang dapat diterapkan tim platform, keamanan, dan produk AI. Cakupannya meliputi siklus hidup kunci, templat inventaris kunci, rotasi tanpa waktu henti, perlindungan CI/CD, panduan penanganan insiden, serta kode untuk membuat, menyimpan, dan memverifikasi kunci. Sumbernya mencakup Lembar Panduan Pengelolaan Rahasia OWASP, praktik terbaik kunci API Google Cloud, dan dokumentasi pemindaian rahasia GitHub, yang semuanya diperiksa pada 27 Oktober 2026.

Praktik terbaik pengelolaan kunci API: daftar periksa singkat

#	Praktik terbaik	Risiko yang dicegah
1	Jangan pernah menanamkan kunci langsung di kode sumber, notebook, atau aplikasi klien	Kebocoran melalui riwayat Git, bundel browser, dan biner seluler
2	Simpan kunci penyedia di server; berikan token sesi berumur pendek kepada klien	Pengambilan kunci dari perangkat oleh pengguna atau malware
3	Gunakan satu kunci untuk setiap lingkungan, aplikasi, dan anggota tim	Satu kebocoran melumpuhkan semuanya saat kunci dicabut
4	Terapkan pembatasan paling ketat yang tersedia: API, model, IP, kuota	Kunci curian dapat digunakan untuk segala keperluan
5	Simpan kunci di pengelola rahasia, bukan di tiket, obrolan, atau wiki	Salinan kunci yang tidak dapat ditemukan atau dirotasi
6	Kelola inventaris kunci beserta penanggung jawab, beban kerja, dan tanggal rotasinya	Rotasi mengganggu sistem pengguna kunci yang tidak diketahui
7	Lakukan rotasi terjadwal dengan masa tumpang tindih, lalu cabut kunci lama	Kunci berumur panjang yang tetap aktif setelah karyawan dan vendor tidak lagi bekerja sama
8	Hapus kunci yang tidak lagi digunakan	Kunci terlupakan yang izinnya masih aktif
9	Aktifkan pemindaian rahasia dan perlindungan push	Kunci masuk ke repositori publik atau bersama
10	Jangan pernah mencatat kunci atau header otorisasi ke log; catat ID atau versi kunci	Rahasia bocor melalui log, trace, dan laporan kesalahan
11	Tetapkan batas pengeluaran dan peringatan untuk penggunaan yang tidak biasa	Tagihan tak terduga akibat kunci yang dicuri atau penggunaannya tak terkendali
12	Siapkan panduan penanganan insiden yang memprioritaskan pencabutan	Paparan berkepanjangan saat tim memperdebatkan apakah kunci yang bocor sudah digunakan

Bagian selanjutnya menjelaskan cara menerapkan setiap praktik untuk beban kerja AI, ketika kunci tidak hanya berfungsi untuk autentikasi, tetapi juga mengizinkan jalur data untuk prompt, dokumen, dan keluaran model.

Siklus hidup kunci API

OWASP menyarankan pengelolaan rahasia sepanjang siklus hidupnya: pembuatan, rotasi, pencabutan, dan kedaluwarsa, dengan audit pada setiap tahap (Lembar Panduan Pengelolaan Rahasia OWASP). Untuk kunci API AI, siklus hidupnya adalah sebagai berikut:

Tahap	Tindakan penanggung jawab	Bukti yang disimpan
Permintaan	Jelaskan kebutuhan beban kerja, lingkungan, dan model	Tiket atau entri inventaris
Pembuatan	Buat melalui konsol atau API penyedia dengan nama yang deskriptif	ID kunci, waktu pembuatan, pembuat
Pembatasan	Batasi model, API, jaringan, dan anggaran	Pengaturan pembatasan
Penyimpanan	Simpan langsung ke pengelola rahasia; jangan pernah menempelkannya di tempat lain	Jalur rahasia dan kebijakan akses
Penyaluran	Suntikkan saat runtime hanya ke beban kerja yang membutuhkannya	Pengikatan deployment
Pemantauan	Pantau permintaan, token, pengeluaran, dan waktu penggunaan terakhir	Dasbor penggunaan dan peringatan
Rotasi	Buat pengganti, alihkan penggunaan, verifikasi	Catatan rotasi
Pencabutan	Nonaktifkan di penyedia, pastikan respons 401	Stempel waktu pencabutan dan hasil pengujian

Lima batas yang dapat dilintasi kunci AI

Mulailah dengan memetakan tempat berpindahnya rahasia atau data yang aksesnya diizinkan oleh rahasia tersebut. Sebagian besar kegagalan terjadi karena tim melindungi kunci penyedia tetapi mengabaikan salah satu batas di sekitarnya.

Batas	Kegagalan yang umum terjadi	Kontrol yang diperlukan
Klien ke aplikasi	Kunci penyedia ditanamkan dalam bundel browser, biner seluler, aplikasi desktop, atau ekstensi	Simpan kunci penyedia di server; terbitkan kredensial pengguna atau sesi berumur pendek untuk klien
Aplikasi ke gateway	Semua layanan berbagi satu kunci tanpa pembatasan	Gunakan identitas beban kerja, token gateway dengan cakupan terbatas, kuota, dan kebijakan rute yang eksplisit
Gateway ke penyedia	Satu kredensial dapat mengakses semua model, proyek, atau lingkungan	Pisahkan kunci berdasarkan penyedia, lingkungan, beban kerja, dan tingkat risiko jika didukung
Permintaan ke log	Header otorisasi, prompt, file, atau keluaran muncul di trace	Masukkan kolom rahasia ke daftar larangan, minimalkan pencatatan payload, tokenisasi pengenal, dan uji penyamaran data
Operasi oleh manusia	Kunci ditempelkan ke tiket, obrolan, panduan operasional, atau alat dukungan	Gunakan alur akses terkontrol, pengambilan yang diaudit, prosedur akses darurat, dan kedaluwarsa otomatis

Peta batas ini mengubah pertanyaan desain dari “Di mana kita menyimpan kunci?” menjadi “Identitas mana yang dapat membuat permintaan apa, dengan data apa, melalui rute mana, dan bukti apa yang tersisa setelahnya?”

Gunakan model pengamanan kunci di server

Kredensial penyedia berumur panjang sebaiknya tidak disalurkan ke klien browser, seluler, desktop, atau ekstensi. Apa pun yang dikirimkan ke perangkat pengguna akhir harus dianggap dapat diambil kembali oleh pengguna tersebut atau malware yang berjalan dengan hak akses yang sama.

Pola yang lebih aman adalah:

Klien melakukan autentikasi ke backend Anda menggunakan sesi pengguna, kredensial perangkat, atau token aplikasi berumur pendek.
Backend Anda mengotorisasi fitur yang diminta dan menerapkan batas per pengguna atau per tenant.
Gateway atau integrasi di server memilih penyedia dan model yang disetujui.
Kunci penyedia diambil saat runtime atau disediakan untuk beban kerja tepercaya melalui platform deployment.
Respons penyedia dikembalikan melalui batas kebijakan yang sama.

Klien tidak pernah membutuhkan rahasia penyedia. Klien hanya menerima wewenang untuk memanggil produk Anda dalam batas yang Anda tetapkan.

Untuk agen pemrograman dan alat pengembang lokal, terapkan prinsip yang sama dengan mekanisme pengecualian yang dirancang secara sengaja. Pengembang mungkin membutuhkan kredensial lokal, tetapi kredensial tersebut sebaiknya merupakan kredensial produk atau gateway yang mendukung pencabutan, atribusi penggunaan, dan cakupan terbatas—bukan kunci penyedia bersama untuk seluruh organisasi yang disalin ke dotfile di seluruh perusahaan.

Buat inventaris kunci sebelum melakukan rotasi apa pun

Proyek rotasi gagal ketika tim tidak mengetahui beban kerja mana yang menggunakan suatu kunci. Buat inventaris yang dapat dibaca mesin dan tetapkan penanggung jawab sebelum mengganti kredensial.

Setidaknya, catat:

Kolom	Contoh	Mengapa penting
ID rahasia	`prod-support-chat-anthropic-01`	Referensi internal yang stabil dan bukan nilai rahasia itu sendiri
Penyedia dan proyek	Akun penyedia + pengenal proyek	Menentukan cakupan dampak eksternal
Lingkungan	Pengembangan, staging, produksi	Mencegah sistem pengujian mewarisi wewenang produksi
Beban kerja	`support-chat-api`	Memungkinkan atribusi dan pencabutan terarah
Penanggung jawab	Tim dan jadwal petugas siaga	Memastikan tanggung jawab yang jelas saat insiden
Lokasi penyimpanan	Jalur pengelola rahasia atau pengikatan deployment	Menunjukkan lokasi sumber acuan utama
Model/rute yang diizinkan	Keluarga model yang disetujui atau kebijakan gateway	Membatasi penggunaan yang tidak diharapkan
Batas pengeluaran dan permintaan	Anggaran beban kerja, RPM, TPM, atau kontrol konkurensi	Membatasi penyalahgunaan dan otomatisasi yang tak terkendali
Waktu pembuatan dan rotasi terakhir	Stempel waktu	Memudahkan identifikasi kredensial yang sudah lama tidak diperbarui
Metode rotasi	Dua kunci, alias versi, atau jendela pemeliharaan	Mencegah perubahan tanpa persiapan
Dependensi pencabutan	Layanan yang harus diperbarui terlebih dahulu	Menjaga ketersediaan
Klasifikasi data	Publik, internal, rahasia, diatur regulasi	Menghubungkan kebijakan kunci dengan tata kelola prompt

Jangan masukkan nilai kunci ke inventaris. Simpan hanya metadata dan referensi ke rahasia yang dikelola.

Pisahkan identitas berdasarkan lingkungan, beban kerja, dan risiko

Pola keliru yang paling umum adalah satu kunci produksi yang digunakan bersama oleh semua layanan. Cara ini memang praktis sampai kunci itu bocor dari satu repositori, runner pengujian, laptop kontraktor, atau transkrip dukungan. Setelah itu, tim tidak dapat mencabut kunci tanpa mengganggu produk lain yang tidak terkait.

Utamakan identitas terpisah untuk:

Produksi, staging, pengembangan, dan pengujian lokal.
Trafik pelanggan, alat internal, tugas batch, dan pipeline evaluasi.
Alur kerja berisiko tinggi yang dapat memanggil alat atau memproses data rahasia.
Unit bisnis atau tenant yang berbeda ketika batas kontraktual mengharuskan pemisahan.
Akses darurat, yang sebaiknya tetap dinonaktifkan atau dikontrol secara ketat selama operasi normal.

Jika penyedia menawarkan pembatasan, terapkan. Pembatasan dapat mencakup API, model, jaringan sumber, proyek, referrer, aplikasi, atau kuota yang diizinkan. Panduan kunci API Google Cloud, misalnya, menyarankan pembatasan dan isolasi kunci, penghapusan kunci yang tidak diperlukan, pencegahan kunci masuk ke commit repositori, serta pemantauan penggunaannya.

Jika penyedia tidak menawarkan kontrol yang cukup terperinci, terapkan melalui gateway Anda sendiri. Gateway terpusat dapat memvalidasi beban kerja pemanggil, memetakannya ke rute yang disetujui, menerapkan anggaran dan batas laju, serta menyimpan kredensial vendor di balik satu batas server yang telah ditinjau. Baca panduan arsitektur gateway API AI yang lebih luas untuk desain perutean dan failover.

Jadikan tata kelola prompt dan log bagian dari pengelolaan kunci

Kunci API mengizinkan suatu jalur data. Melindungi kunci tanpa mengontrol jalur tersebut membuat risiko utama yang khas pada AI tetap belum teratasi.

Sebelum merutekan permintaan, klasifikasikan payload dan terapkan aturan hanya menggunakan data minimum yang diperlukan:

Hapus kredensial, token, cookie, kunci privat, dan string koneksi.
Singkirkan kolom yang tidak dibutuhkan model.
Tokenisasi atau samarkan pengenal langsung dengan nama samaran jika tugas dapat dijalankan tanpanya.
Tolak data yang diatur regulasi atau dibatasi kontrak jika pemrosesannya tidak didukung.
Pisahkan instruksi sistem dari konten pengguna atau konten hasil pengambilan yang tidak tepercaya.
Validasi argumen alat sebelum agen dapat memanggil sistem eksternal.

Log memerlukan skema yang eksplisit. Jangan mengandalkan ingatan pengembang untuk tidak mencatat objek permintaan ke log. Tentukan kolom yang diizinkan, lalu buang atau ubah semua kolom lainnya.

Catatan peristiwa produksi yang berguna dapat memuat:

{
  "request_id": "req_01J...",
  "tenant_id_hash": "tnt_7f2...",
  "workload": "support-chat-api",
  "route_policy": "support-low-risk-v3",
  "provider": "selected-provider",
  "model": "selected-model",
  "input_tokens": 842,
  "output_tokens": 211,
  "latency_ms": 1370,
  "status": 200,
  "key_version": "v12",
  "redaction_policy": "customer-support-v4"
}

Secara default, catatan tersebut tidak boleh memuat header otorisasi, kunci penyedia mentah, prompt lengkap, dokumen yang diunggah, argumen alat yang belum disamarkan, atau seluruh keluaran model. Jika perekaman payload diperlukan untuk evaluasi atau insiden yang dikontrol secara ketat, batasi waktunya, kontrol aksesnya, dan pisahkan dengan jelas dari telemetri rutin.

Lembar Panduan Pencatatan Log OWASP memberikan acuan yang berguna untuk mengecualikan token akses, kata sandi, kunci enkripsi, dan data sensitif lainnya dari log aplikasi.

Rancang rotasi kunci API tanpa waktu henti

Rotasi hanya menjadi kontrol yang efektif jika dapat dilakukan dengan aman. Panduan operasional yang menyebabkan gangguan layanan akan terus ditunda hingga terjadi keadaan darurat.

Gunakan urutan dua kunci atau rahasia berversi jika penyedia mendukung kredensial yang aktif bersamaan:

Buat kunci penyedia baru. Terapkan pembatasan yang sama atau lebih ketat daripada kunci lama.
Simpan sebagai versi rahasia baru. Jangan menimpa nilai lama secara langsung jika platform Anda mendukung versi atau alias.
Deploy komponen pembaca yang mendukung versi baru. Perbarui gateway atau beban kerja agar mengambil kunci dari alias atau versi yang berlaku.
Alihkan trafik dan pantau. Pastikan permintaan berhasil, model sesuai harapan, serta pengeluaran, batas laju, dan tingkat kesalahan sesuai menggunakan versi kunci baru.
Hentikan penggunaan oleh komponen lama. Periksa inventaris deployment, tugas, worker, dan lingkungan pemulihan bencana.
Cabut kunci lama. Jangan hanya berhenti menggunakannya; nonaktifkan di penyedia.
Verifikasi penolakan. Pengujian terkontrol harus memastikan bahwa kredensial lama tidak lagi berfungsi.
Catat bukti. Simpan stempel waktu, penanggung jawab, beban kerja terdampak, hasil validasi, dan tanggal tinjauan berikutnya.

Untuk sistem yang mendukung pemilihan versi kunci, aplikasi sebaiknya merujuk ke alias yang stabil alih-alih menanamkan versi rahasia secara langsung dalam kode:

type ProviderCredential = {
  value: string;
  version: string;
};

async function loadProviderCredential(): Promise<ProviderCredential> {
  const activeVersion = await secretStore.resolveAlias("ai/provider/active");
  const value = await secretStore.readVersion("ai/provider", activeVersion);

  return { value, version: activeVersion };
}

Jangan mencetak value, menserialisasi objek yang dikembalikan, atau melampirkannya ke kesalahan. Catat hanya pengenal versi yang bukan rahasia.

Lembar Panduan Pengelolaan Rahasia OWASP menyarankan perencanaan seluruh siklus hidup rahasia, termasuk pembuatan, rotasi, pencabutan, kedaluwarsa, audit, pencadangan, dan akses darurat. Panduan ini juga menekankan otomatisasi rotasi jika memungkinkan.

Cegah rahasia masuk ke repositori dan log CI

Pengelola rahasia tidak dapat membantu setelah kredensial disalin ke kode sumber, fixture, artefak build, atau transkrip CI.

Terapkan kontrol pada tiga tahap:

Sebelum commit

Sediakan file .env.example dengan placeholder, jangan pernah berisi kredensial yang berfungsi.
Jauhkan file rahasia lokal dari kontrol versi.
Jalankan pemindai rahasia yang cepat dalam hook pre-commit untuk pola penyedia yang umum dan nilai berentropi tinggi.
Ajarkan kepada pengembang bahwa menghapus rahasia dalam commit berikutnya tidak menghapusnya dari riwayat.

Saat push dan pull request

Aktifkan pemindaian rahasia repositori dan perlindungan push jika tersedia.
Tambahkan pola khusus untuk token gateway internal yang tidak dikenali pemindai publik.
Wajibkan dokumentasi alasan pengecualian dan arahkan pengecualian tersebut untuk ditinjau tim keamanan.
Pindai file hasil generasi, notebook, snapshot pengujian, dan rencana infrastruktur—bukan hanya kode sumber aplikasi.

GitHub mendokumentasikan perlindungan push sebagai cara untuk memindai selama proses push dan memblokir rahasia yang terdeteksi sebelum masuk ke repositori. Deteksi bukan alasan untuk mempertahankan kunci: anggap setiap kredensial yang dipastikan telah masuk ke commit sebagai terekspos dan lakukan rotasi.

Selama CI/CD

Utamakan identitas beban kerja atau federasi berumur pendek daripada kredensial cloud yang disimpan.
Berikan rahasia hanya kepada tugas dan langkah yang membutuhkannya.
Samarkan nilai rahasia yang diketahui, tetapi jangan mengandalkan penyamaran sebagai kontrol utama.
Nonaktifkan pelacakan shell saat mengambil rahasia.
Cegah kode dari fork yang tidak tepercaya mengakses rahasia deployment.
Tinjau artefak, cache, dump crash, dan laporan pengujian untuk menemukan rahasia yang terekam tanpa sengaja.

Pantau penggunaan tanpa mencatat rahasia

Pemantauan yang baik menjawab “siapa menggunakan wewenang apa?” tanpa merekam kredensial pemberi wewenang itu sendiri.

Pantau:

Beban kerja, lingkungan, tenant atau proyek, dan versi kunci.
Penyedia, model, kebijakan rute, dan jalur cadangan.
Jumlah permintaan, volume token, pengeluaran, latensi, dan kategori kesalahan.
Jaringan sumber atau identitas deployment jika berguna.
Akses ke pengelola rahasia, termasuk upaya pembacaan yang ditolak.
Pembuatan kunci, perubahan pembatasan, rotasi, pencabutan, dan penghapusan.
Penggunaan mendadak dari lingkungan, wilayah geografis, model, atau rentang waktu yang tidak diharapkan.

Atur peringatan berdasarkan perilaku, bukan hanya total pengeluaran. Kunci curian dengan anggaran rendah tetap dapat mengekspos prompt atau menyelidiki alur kerja internal. Sebaliknya, tugas batch yang sah dapat menyebabkan lonjakan pengeluaran tanpa kompromi kredensial. Korelasikan penggunaan penyedia dengan ID permintaan aplikasi, keputusan kebijakan gateway, peristiwa deployment, dan log audit pengelola rahasia.

Untuk kontrol trafik yang melengkapi kontrol kredensial, gunakan panduan batas laju LLM dan panduan operasional perutean cadangan API LLM.

Ukur waktu insiden dari paparan hingga pencabutan

Ketika kunci mungkin terekspos, tujuan pertama adalah membatasi dampak—bukan membuktikan apakah penyerang telah menggunakannya.

Jalankan urutan berikut:

Tandai kredensial sebagai mencurigakan. Catat kapan dan di mana kredensial tersebut mungkin terekspos.
Buat pengganti melalui jalur terkontrol yang biasa digunakan. Jangan menempelkan kunci baru ke obrolan demi mempercepat penanganan insiden.
Alihkan beban kerja yang sah ke pengganti. Gunakan prosedur rotasi yang telah disiapkan.
Cabut kunci yang dicurigai. Jika pencabutan langsung akan menimbulkan dampak yang tidak dapat diterima, isolasi rute dan kurangi batas sambil menyelesaikan peralihan.
Telusuri setiap lokasi salinan. Periksa riwayat kode sumber, log CI, artefak, lapisan container, sistem dukungan, dasbor, notebook, konfigurasi lokal, dan cadangan.
Tinjau jalur data yang diizinkan. Tentukan prompt, keluaran, file, alat, atau model mana yang dapat diakses kunci—bukan hanya cakupan penagihannya.
Korelasikan aktivitas. Bandingkan penggunaan penyedia, log gateway, deployment, pembacaan rahasia, dan aktivitas pengguna.
Beri tahu penanggung jawab yang tepat. Libatkan tim keamanan, platform, hukum, privasi, dan pelanggan sesuai data dan kontrak yang terkait.
Atasi akar masalah. Tambahkan pemindai, pembatasan, batas identitas, atau filter log yang belum tersedia.
Ukur durasinya. Catat waktu hingga deteksi, penggantian, peralihan trafik, pencabutan, dan verifikasi.

Metrik yang paling dapat ditindaklanjuti sering kali adalah waktu dari paparan hingga pencabutan: berapa lama kredensial yang dicurigai tetap dapat digunakan setelah organisasi memiliki bukti paparan yang dapat dipercaya. Memperpendek interval itu membutuhkan penanggung jawab yang siap, inventaris, otomatisasi, dan rotasi yang telah diuji—bukan dokumen kebijakan yang lebih panjang.

Jika Anda menerbitkan kunci API untuk pelanggan sendiri

Banyak produk AI juga membagikan kunci, misalnya agar pelanggan dapat memanggil agen Anda atau menyematkan fitur Anda. Praktik terbaik yang sama berlaku dari sisi penerbit:

Buat kunci dengan generator acak yang aman secara kriptografis, dengan entropi setidaknya 32 byte.
Tambahkan prefiks yang mudah dikenali (seperti sk-fk- pada kunci Flatkey) agar pemindai rahasia dan tim dukungan Anda dapat mengidentifikasi kunci yang bocor. Program mitra GitHub menggunakan format token yang dikenal untuk memberi tahu penerbit saat kunci di-push ke repositori publik (pemindaian rahasia GitHub).
Tampilkan kunci lengkap hanya sekali, lalu simpan hanya hash-nya. Jika basis data Anda bocor, kunci tetap aman.
Tampilkan hanya prefiks yang disamarkan di dasbor Anda, beserta tanggal pembuatan dan waktu penggunaan terakhir.
Berlakukan pencabutan seketika dan kembalikan 401 untuk kunci yang dicabut.
Izinkan pelanggan membatasi cakupan kunci ke model, proyek, atau batas pengeluaran tertentu.

Python: membuat, melakukan hash, dan memverifikasi kunci

import hashlib
import hmac
import secrets

PREFIX = "sk-acme-"

def new_api_key() -> tuple[str, str]:
    """Return (plaintext key shown to the user once, hash to store)."""
    key = PREFIX + secrets.token_urlsafe(32)  # 32 random bytes
    return key, hashlib.sha256(key.encode()).hexdigest()

def verify(presented: str, stored_hash: str) -> bool:
    candidate = hashlib.sha256(presented.encode()).hexdigest()
    return hmac.compare_digest(candidate, stored_hash)  # constant-time compare

key, digest = new_api_key()
print(key[:12] + "...")   # show the full key once in the UI, never log it
print(verify(key, digest))  # True

Hash cepat seperti SHA-256 dapat digunakan di sini karena kuncinya panjang dan acak, berbeda dengan kata sandi buatan manusia. Simpan hash, ID kunci, pemilik, cakupan, dan stempel waktu.

Node.js: memuat kunci dari lingkungan dan menolak akses jika gagal

// Never fall back to a hardcoded default key.
const apiKey = process.env.FLATKEY_API_KEY;
if (!apiKey || !apiKey.startsWith("sk-fk-")) {
  throw new Error("FLATKEY_API_KEY is missing or malformed");
}

const res = await fetch("https://router.flatkey.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-haiku-5-5",
    messages: [{ role: "user", content: "ping" }],
    max_tokens: 5,
  }),
});
console.log(res.status); // log the status, never the header

Pastikan kunci yang dicabut benar-benar tidak berfungsi

Pencabutan baru terbukti ketika kunci lama gagal digunakan. Setelah setiap rotasi atau insiden, jalankan pemeriksaan seperti ini dari mesin tepercaya:

# Expect 401 for the revoked key; do not echo the key itself
OLD_KEY="$(cat /run/secrets/old_flatkey_key)"
status=$(curl -s -o /dev/null -w "%{http_code}" \
  https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $OLD_KEY")
if [ "$status" = "401" ]; then echo "revoked OK"; else echo "STILL ACTIVE: $status"; fi

Catat hasil dan waktunya dalam log rotasi Anda. Flatkey mendokumentasikan bahwa pencabutan berlaku seketika dan setiap permintaan dengan kunci yang dicabut menerima 401 Unauthorized, tanpa masa tenggang (dokumentasi kunci API Flatkey).

Cara Flatkey mendukung praktik terbaik ini

Flatkey menyediakan satu endpoint yang kompatibel dengan OpenAI (https://router.flatkey.ai/v1) untuk banyak penyedia model, sehingga lebih sedikit kunci penyedia tersebar di seluruh layanan Anda. Menurut dokumentasi kunci API Flatkey (diperiksa pada 27 Oktober 2026):

Anda dapat membuat beberapa kunci: satu untuk setiap lingkungan, aplikasi, atau anggota tim, dengan nama deskriptif seperti prod-customer-chatbot.
Kunci sk-fk- lengkap hanya ditampilkan sekali. Setelah itu, halaman Kunci menampilkan nama, tanggal pembuatan, stempel waktu penggunaan terakhir, dan prefiks yang disamarkan.
Pencabutan berlaku seketika, jadi deploy kunci pengganti sebelum mencabut kunci lama.
Semua kunci berbagi saldo akun dan secara default dapat mengakses semua model. Gunakan Grup di konsol untuk membatasi kunci ke model tertentu atau menetapkan kuota pengeluaran.

Dokumentasi penggunaan menjelaskan log per permintaan yang mencakup model, token, biaya, dan kunci, ditambah batas pengeluaran bulanan serta peringatan email saat saldo rendah, yang mendukung praktik 10 dan 11. Untuk organisasi yang lebih besar, dokumentasi perusahaan Flatkey menjelaskan subkunci berstruktur pohon dengan anggaran dan daftar model yang diizinkan untuk masing-masing subkunci. Gateway tidak menggantikan autentikasi klien, klasifikasi data, dan kedisiplinan pencatatan log Anda sendiri, jadi tetap terapkan bagian lain dari daftar periksa ini. Untuk memulai, lihat panduan awal integrasi Flatkey.

Arsitektur acuan untuk produk AI dengan banyak penyedia

Konfigurasi aman dengan banyak penyedia dapat disusun menjadi lima lapisan:

Lapisan identitas klien: mengautentikasi pengguna, perangkat, agen, atau aplikasi tanpa mengekspos kredensial penyedia.
Lapisan otorisasi aplikasi: memverifikasi hak penggunaan produk, batas tenant, akses fitur, dan anggaran.
Lapisan kebijakan data: mengklasifikasikan dan menyamarkan prompt, file, konteks hasil pengambilan, dan argumen alat.
Lapisan gateway dan perutean: memilih model yang disetujui, menerapkan kuota, mencatat atribusi tanpa rahasia, dan menangani failover.
Lapisan kredensial penyedia: menyimpan kredensial vendor secara terisolasi, merotasi versi, dan menyediakannya hanya untuk beban kerja perutean tepercaya.

Desain ini membatasi cakupan dampak. Token klien yang disusupi tidak otomatis mengungkap kunci penyedia. Identitas beban kerja yang disusupi seharusnya tidak memberikan akses ke semua penyedia. Kredensial penyedia yang bocor seharusnya tidak mengizinkan akses ke semua lingkungan. Kegagalan pencatatan log seharusnya tidak mengekspos rahasia sekaligus seluruh payload.

Daftar periksa produksi

Gunakan daftar periksa ini sebelum peluncuran dan saat tinjauan kontrol triwulanan.

Pengamanan dan identitas

[ ] Tidak ada kunci penyedia berumur panjang yang disertakan dalam kode browser, seluler, desktop, atau ekstensi.
[ ] Setiap beban kerja produksi memiliki penanggung jawab dan jalur kredensial yang dapat diidentifikasi.
[ ] Akses produksi, staging, pengembangan, evaluasi, dan lokal dipisahkan.
[ ] Kunci bersama untuk pengguna manusia telah diganti dengan identitas beban kerja atau gateway jika memungkinkan.
[ ] Pembatasan penyedia dan gateway diatur ke cakupan paling sempit yang dapat diterapkan.

Penyimpanan dan penyaluran

[ ] Sumber acuan utama adalah penyimpanan rahasia terkelola atau pengikatan deployment yang terkontrol.
[ ] Aplikasi mengambil rahasia hanya saat runtime dan tidak mencetak atau menserialisasinya.
[ ] Tugas CI hanya menerima rahasia yang diperlukan untuk langkah yang membutuhkannya.
[ ] Akses rahasia dan perubahan administratif diaudit.
[ ] Akses darurat didokumentasikan, dibatasi waktunya, dan diuji.

Data dan observabilitas

[ ] Header otorisasi dan nilai kunci dikecualikan dari log, trace, kesalahan, dan ekspor dukungan.
[ ] Pencatatan prompt, keluaran, file, dan argumen alat mengikuti skema daftar yang diizinkan.
[ ] Penyamaran dilakukan sebelum perutean ke banyak penyedia.
[ ] Penggunaan dapat diatribusikan ke beban kerja, lingkungan, rute, penyedia, model, dan versi kunci.
[ ] Peringatan mencakup rute dan identitas yang tidak biasa, serta pengeluaran.

Rotasi dan respons

[ ] Tersedia panduan rotasi dua kunci atau rahasia berversi yang telah diuji.
[ ] Kunci lama dicabut di penyedia dan diverifikasi tidak dapat digunakan.
[ ] Pemindaian rahasia dan perlindungan push mencakup repositori dan artefak hasil generasi.
[ ] Dugaan kebocoran memicu pembatasan dampak segera tanpa menunggu bukti penyalahgunaan.
[ ] Waktu dari paparan hingga pencabutan diukur setelah simulasi dan insiden.

Pertanyaan umum

Apa saja praktik terbaik pengelolaan kunci API?

Jauhkan kunci dari kode sumber dan aplikasi klien, gunakan kunci terpisah untuk setiap lingkungan dan beban kerja, batasi setiap kunci ke API, model, dan anggaran yang dibutuhkan, simpan kunci di pengelola rahasia, lakukan rotasi sesuai jadwal yang telah diuji, hapus kunci yang tidak digunakan, aktifkan pemindaian rahasia, jangan pernah mencatat kunci ke log, dan segera cabut ketika ada dugaan kebocoran.

Apakah kunci API sebaiknya disimpan dalam variabel lingkungan?

Variabel lingkungan merupakan cara yang wajar untuk menyalurkan kunci ke proses, tetapi bukan sistem pengelolaan. Nilainya sebaiknya berasal dari pengelola rahasia atau mekanisme injeksi rahasia platform Anda, disertai kontrol akses, rotasi, dan audit. Jangan pernah memasukkan file .env ke commit.

Seberapa sering kunci API perlu dirotasi?

Pilih interval berdasarkan risiko dan kontrol penyedia Anda; banyak tim merotasi kunci AI produksi setiap 90 hari dan segera melakukan rotasi setelah pergantian staf atau dugaan paparan. Yang paling penting adalah rotasi telah dilatih, kunci lama dicabut, dan pencabutannya diverifikasi.

Bisakah browser atau aplikasi seluler memanggil penyedia AI secara langsung dengan kunci API?

Hindari cara ini. Apa pun yang dikirim ke perangkat dapat diekstrak. Minta klien melakukan autentikasi ke backend Anda, lalu biarkan backend atau gateway memanggil model dengan kunci di server dan batas per pengguna.

Apa yang harus saya lakukan jika kunci API bocor di GitHub?

Anggap kunci sudah disusupi. Buat pengganti, pindahkan beban kerja ke kunci tersebut, cabut kunci yang bocor, pastikan kunci itu mengembalikan 401, tinjau penggunaan selama periode paparan, dan tambahkan pemindaian atau perlindungan push agar tidak terulang. Menghapus commit tidak membuat kunci kembali aman.

Apakah satu kunci gateway lebih aman daripada banyak kunci penyedia?

Cara ini mengurangi jumlah rahasia dalam kode Anda, tetapi memusatkan wewenang. Gunakan kunci gateway terpisah untuk setiap lingkungan dan beban kerja, batasi cakupannya dengan batas model dan pengeluaran, serta lindungi kunci penyedia di balik gateway dengan ketelitian yang sama seperti sebelumnya.

Bagaimana sebaiknya saya menyimpan kunci API yang diterbitkan untuk pengguna saya sendiri?

Simpan hanya hash setiap kunci, tampilkan kunci lengkap hanya sekali saat pembuatan, tampilkan prefiks yang disamarkan setelahnya, dan dukung pencabutan seketika.