Bagian I - Bab 3

Keamanan Kredensial: API Key dan File .env

Cara menyimpan dan mengelola API Key dengan benar, memahami risiko kebocoran, dan mendiagnosis error autentikasi.

3.1 Apa itu API Key dan Bagaimana Ia Bekerja

Ketika kamu menggunakan layanan AI seperti Gemini atau OpenAI, setiap request yang kamu kirim harus bisa diidentifikasi: siapa yang mengirimnya, apakah ia punya izin, dan berapa biaya yang harus ditagihkan. Mekanisme identifikasi ini menggunakan API Key, sebuah string acak yang panjang yang diberikan penyedia layanan secara unik untuk setiap akun.

Cara kerjanya sederhana: setiap request yang kamu kirim ke API menyertakan API Key di dalam header-nya. Server penyedia layanan membaca key tersebut, memvalidasinya, dan memutuskan apakah request boleh diproses.

Yang perlu dipahami dari diagram ini: API Key adalah identitas kamu di mata penyedia layanan. Siapapun yang memegang API Key-mu bisa menggunakannya seolah-olah mereka adalah kamu, dan tagihannya tetap masuk ke akunmu.

3.2 Risiko Kebocoran API Key

Kebocoran API Key bukan skenario yang jarang terjadi. Ada bot yang secara aktif memindai repositori GitHub publik setiap menit, mencari string yang cocok dengan pola API Key dari berbagai penyedia layanan. Waktu antara key terunggah ke GitHub dan key tersebut disalahgunakan bisa sesingkat beberapa menit.

Berikut adalah tiga sumber kebocoran yang paling umum beserta konsekuensinya.

1. Hardcode Langsung di dalam Kode, Risiko Tertinggi

Seperti apa ini: menulis API Key langsung sebagai string di dalam file Python, lalu mengunggah file tersebut ke repositori GitHub publik, misalnya:

api_key = "AIzaSyD3x9k..."
client = Gemini(api_key=api_key)

Konsekuensi: bot pemindai GitHub bisa mendeteksi dan mengekstrak key dalam hitungan menit. Key bisa digunakan untuk membuat ribuan request, semua ditagihkan ke akunmu. Beberapa penyedia layanan secara otomatis menonaktifkan key yang terdeteksi bocor, tapi kerusakannya mungkin sudah terjadi.

2. Menyimpan di File yang Tidak Masuk .gitignore

Seperti apa ini: menyimpan key di file konfigurasi Python, misalnya config.py, settings.json, atau file lain yang tidak diabaikan oleh Git, sehingga ikut terunggah ke GitHub. Contohnya:

# config.py
GEMINI_KEY = "AIzaSyD3x9k..."
PINECONE_KEY = "pcsk_abc123..."

Konsekuensi: sama dengan hardcode, key tersedia publik di GitHub. Bahkan setelah file dihapus dari repositori, riwayat commit Git masih menyimpannya kecuali riwayat tersebut dihapus secara eksplisit.

3. Membagikan Key via Chat atau Email

Seperti apa ini: mengirim API Key melalui WhatsApp, Slack, email, atau screenshot untuk "sementara" membantu rekan tim, lalu lupa mencabut akses atau mengganti key-nya.

Konsekuensi: key yang dibagikan via platform komunikasi bisa diakses oleh siapapun yang memiliki akses ke riwayat chat tersebut, termasuk pihak ketiga jika akun diretas. Key yang "dipinjam sementara" sering berujung menjadi permanen.

3.3 Solusi: File .env dan python-dotenv

Pendekatan standar industri untuk menyimpan kredensial adalah memisahkannya dari kode sepenuhnya, menyimpannya di file konfigurasi yang tidak pernah masuk ke dalam sistem version control.

File .env adalah file teks biasa yang berisi pasangan nama-nilai untuk variabel konfigurasi sensitif. Ia tidak memiliki ekstensi khusus, namanya memang hanya .env. Library python-dotenv membaca file ini dan memuatnya ke dalam environment variables Python saat program dijalankan.

Implementasi lengkapnya terdiri dari empat file yang bekerja bersama.

.env, Menyimpan Semua Kredensial Sensitif (Tidak Masuk Git)

File ini menyimpan semua kredensial sensitif. Letakkan di root direktori proyek.

# API Keys, jangan pernah bagikan file ini
GEMINI_API_KEY="AIzaSyD3x9kExampleKey123"
PINECONE_API_KEY="pcsk_abc123ExampleKey456"
PINECONE_INDEX="nama-index-kamu"

# Konfigurasi lain yang sensitif
DATABASE_URL="postgresql://user:password@host/db"
LANGSMITH_API_KEY="ls__example789"

.gitignore, Memberitahu Git File Mana yang Harus Diabaikan

File ini memberitahu Git file dan direktori mana yang harus diabaikan. Pastikan .env dan venv/ selalu ada di sini.

# Kredensial, wajib ada
.env

# Virtual environment, wajib ada (lihat Bab 2)
venv/
.venv/

# File sistem
.DS_Store
__pycache__/
*.pyc
*.pyo

# Cache Python
*.egg-info/
dist/
build/

# IDE
.vscode/settings.json
.idea/

main.py, Cara yang Benar Memanggil API Key

Cara yang benar memanggil API Key di dalam kode Python. Tidak ada string key yang muncul di file ini.

import os
from dotenv import load_dotenv

# Muat variabel dari file .env ke environment
# Harus dipanggil sebelum os.getenv() digunakan
load_dotenv()

# Ambil nilai dari environment, bukan dari hardcode
gemini_key = os.getenv("GEMINI_API_KEY")
pinecone_key = os.getenv("PINECONE_API_KEY")

# Validasi: pastikan key tidak None sebelum digunakan
if not gemini_key:
    raise ValueError(
        "GEMINI_API_KEY tidak ditemukan. "
        "Pastikan file .env sudah ada dan berisi key yang valid."
    )

# Gunakan key untuk inisialisasi client
# Key tidak pernah ditulis langsung sebagai string di sini
client = GeminiClient(api_key=gemini_key)

.env.example, Boleh Masuk Git karena Tanpa Nilai Nyata

File ini boleh masuk ke Git, ia adalah template tanpa nilai nyata. Rekan tim atau klien menggunakannya sebagai panduan untuk membuat file.env mereka sendiri.

# Salin file ini menjadi .env lalu isi dengan key milikmu
# cp .env.example .env

GEMINI_API_KEY="masukkan_api_key_gemini_kamu_di_sini"
PINECONE_API_KEY="masukkan_api_key_pinecone_kamu_di_sini"
PINECONE_INDEX="masukkan_nama_index_kamu_di_sini"
DATABASE_URL="masukkan_url_database_kamu_di_sini"
LANGSMITH_API_KEY="masukkan_api_key_langsmith_kamu_di_sini"

3.4 Menangani Error Terkait API Key

Dua error yang paling sering muncul terkait API Key memiliki penyebab yang berbeda dan cara diagnosis yang berbeda pula.

401 Unauthorized, API Key Tidak Dikenali atau Tidak Valid

Penyebab umum: key salah disalin (ada spasi tersembunyi, karakter terpotong), file .env tidak ditemukan, load_dotenv() tidak dipanggil sebelum os.getenv(), atau nama variabel di kode berbeda dari nama di file .env.

Langkah diagnosis: (1) Print nilai key dengan print(repr(gemini_key)). Jika hasilnya None, load_dotenv() gagal menemukan file .env. (2) Periksa nama variabel di .env dan di os.getenv() harus identik termasuk huruf kapital. (3) Pastikan file .env ada di direktori yang sama dengan file Python yang menjalankan load_dotenv().

429 Too Many Requests, Quota Habis atau Rate Limit Terlampaui

Penyebab umum: terlalu banyak request dalam waktu singkat (loop tanpa jeda yang memanggil API), quota harian atau bulanan habis, atau tier akun gratis memiliki batas yang lebih ketat dari yang diperkirakan.

Langkah diagnosis: (1) Buka dashboard penyedia API dan periksa penggunaan quota saat ini. (2) Jika ada loop yang memanggil API, tambahkan jeda: import time; time.sleep(1) di antara request. (3) Pertimbangkan beralih ke model yang lebih ringan untuk development dan testing, simpan model berat untuk produksi.

Kesalahan Umum

Ringkasan Bab 3