Kunci API (halaman Developers) — Akun & SSO

🌐 Terjemahan ini sedang ditinjau oleh komunitas. Menemukan kesalahan atau frasa yang kurang alami? Klik Edit halaman ini di GitHub di bawah untuk mengusulkan perbaikan.

Jika Anda membangun sesuatu di atas Quran Gallery — proyek sampingan, dasbor pribadi, skrip otomasi — Anda bisa menghasilkan kunci API pribadi yang membuktikan permintaan berasal dari Anda, tanpa perlu sesi peramban.

Kunci API dikelola seluruhnya dari halaman Developers di akun Anda.

Halaman Developers menampilkan blok Quick Start, form Create Key, dan daftar Keys

Cara mencapai halaman Developers

Masuk ke accounts.qurangallery.com, lalu pergi ke accounts.qurangallery.com/developers.

Apa itu kunci API

Kunci API adalah string rahasia panjang seperti:

qg_abc123def456...

Awalan qg_ menandainya sebagai kunci Quran Gallery. Saat Anda mengirimnya di header Authorization: Bearer ... ke permintaan Quran Gallery, server memperlakukan permintaan seolah-olah Anda yang melakukannya. Jadi kunci API efektif adalah kata sandi ke akun Anda yang dilingkup untuk pemakaian programatik — perlakukan seperti itu.

Membuat kunci

Di halaman Developers, temukan kartu Create New Key.
Ketik nama deskriptif — "Madrasah progress export script", "My Raspberry Pi dashboard", "Local dev". Nama hanya untuk Anda — muncul di daftar kunci.
Klik Create key.

Kunci baru muncul di atas halaman dalam kartu hijau dengan nilai kunci lengkap. Ini satu-satunya kali Anda akan melihat kunci lengkap. Klik ikon salin untuk menyimpannya ke clipboard, lalu simpan di tempat aman.

Halaman Developers setelah membuat kunci — kartu API Key Created hijau menampilkan kunci lengkap, peringatan untuk menyalinnya sekarang, tombol salin, dan tombol Done

Setelah Anda klik Done, kartu hijau hilang, dan sejak saat itu hanya beberapa karakter pertama (start) yang terlihat di daftar. Tidak ada cara untuk mengambil nilai lengkap lagi — jika hilang, buat kunci baru dan hapus yang lama.

Daftar kunci

Di bawah form pembuatan, Anda melihat setiap kunci yang ada di akun Anda.

Halaman Developers setelah menutup kartu hijau, menampilkan daftar API Keys dengan satu entri — nama, pil status Active, prefix kunci, tanggal pembuatan, dan ikon tempat sampah

Untuk tiap kunci:

Nama — yang Anda ketik saat membuat.
Status — Active (pil hijau) atau Disabled (pil abu-abu).
Start — beberapa karakter pertama, seperti qg_abc12.... Cukup untuk mengidentifikasi tanpa membocorkan rahasia.
Created — tanggal pembuatan.

Di kanan tiap baris, ikon tempat sampah menghapus kunci. Penghapusan permanen dan segera — skrip atau aplikasi yang memakai kunci dihapus mulai mendapat 401 di permintaan berikutnya.

Menggunakan kunci

Kirim di header Authorization pada permintaan:

Authorization: Bearer qg_abc123def456...

Kartu penggunaan di halaman Developers menampilkan format persis untuk disalin. Kunci yang sama mengotentikasi Anda di setiap layanan Quran Gallery yang mendukung autentikasi kunci.

Permintaan dengan kunci API melewati sesi peramban, jadi Anda bisa memakainya dari job CI, tugas terjadwal, aplikasi mobile.

Batas laju

Setiap kunci API dibatasi pada 60 permintaan per menit, sliding window. Itu cukup untuk pemakaian pribadi dan kebanyakan skrip. Jika melebihi, API mengembalikan HTTP 429 dengan header yang menunjukkan kapan Anda boleh mencoba lagi.

Kunci API untuk akun yang ditangguhkan atau dihapus segera berhenti bekerja.

Memutar kunci

Praktik terbaik adalah memutar kunci kapan pun:

Laptop atau perangkat dengan kunci hilang atau dijual.
Anda berbagi kunci dengan kolaborator yang tidak lagi memerlukan akses.
Sudah lama dan Anda lebih suka tidak punya rahasia non-rotasi.

Rotasi adalah alur dua-langkah manual:

Buat kunci baru dengan nama deskriptif.
Perbarui skrip/aplikasi Anda untuk memakai kunci baru.
Setelah semua di kunci baru, hapus yang lama.

Belum ada fitur rotasi otomatis.

Saya kehilangan kunci

Quran Gallery tidak bisa mengambil kunci yang hilang. Hapus kunci lama dari daftar dan buat yang baru. Perbarui skrip Anda.

Daftar periksa keamanan

Jangan pernah commit kunci ke git. Pakai file .env (dan tambahkan ke .gitignore).
Jangan pernah tempel kunci di Slack publik, Discord, GitHub issue, atau chat AI. Perlakukan kunci persis seperti kata sandi.
Pakai satu kunci per proyek, bukan satu untuk semua.
Jika curiga kunci kompromi, hapus dulu, lalu buat baru. Urutan penting.
Jangan tanam kunci di kode sisi klien (JavaScript yang berjalan di peramban pengguna, binary aplikasi mobile).

Error umum

Error	Solusi
401 Unauthorized saat memanggil API	Kunci dihapus, dinonaktifkan, atau tidak pernah dibuat. Buat baru.
403 Account suspended	Akun pemilik kunci ditangguhkan. Lihat Akun ditangguhkan.
429 Too Many Requests	Anda menyentuh batas per-menit. Mundur dan coba lagi.
“Failed to load API keys” di halaman	Error jaringan sementara. Refresh.