Pelajari cara menggunakan dan mengelola kunci API untuk Firebase

Kunci API adalah string unik yang digunakan untuk merutekan permintaan ke project Firebase Anda saat berinteraksi dengan layanan Firebase dan Google. Halaman ini menjelaskan informasi dasar tentang kunci API serta praktik terbaik untuk menggunakan dan mengelola kunci API dengan aplikasi Firebase.

Informasi umum tentang kunci API dan Firebase

Kunci API untuk Firebase berbeda dengan kunci API biasa

Tidak seperti cara kunci API biasanya digunakan, kunci API untuk layanan Firebase tidak digunakan untuk mengontrol akses ke resource backend. Hal tersebut hanya dapat dilakukan dengan Firebase Security Rules (untuk mengontrol pengguna akhir yang dapat mengakses resource) dan Firebase App Check (untuk mengontrol aplikasi yang dapat mengakses resource).

Biasanya, Anda harus melindungi kunci API dengan cermat (misalnya, menggunakan layanan vault atau menyetel kunci sebagai variabel lingkungan); tetapi, kunci API untuk layanan Firebase boleh disertakan dalam file konfigurasi yang telah di-check-in atau kode.

Meskipun kunci API untuk layanan Firebase aman untuk disertakan dalam kode, Anda harus meninjau dan menerapkan batasan dan pembatasan yang sesuai untuk kunci tersebut.

Membuat kunci API

Project Firebase dapat memiliki banyak kunci API, tetapi setiap kunci API hanya dapat dikaitkan dengan satu project Firebase.

Kunci API secara otomatis dibuat oleh Firebase untuk Aplikasi Firebase Anda

Firebase secara otomatis membuat kunci API untuk project Anda jika Anda melakukan salah satu dari tindakan berikut:

  • Membuat project Firebase > Browser key dibuat otomatis
  • Membuat Aplikasi Apple Firebase > iOS key dibuat otomatis
  • Membuat Aplikasi Android Firebase > Android key dibuat otomatis

Anda juga dapat membuat kunci API sendiri di Google Cloud console, misalnya untuk pengembangan atau proses debug. Pelajari lebih lanjut kapan hal ini disarankan nanti di halaman ini.

Menemukan kunci API

Anda dapat melihat dan mengelola semua kunci API project di panel APIs & Services > Credentials di Google Cloud console.

Anda juga dapat menemukan kunci API mana yang otomatis dicocokkan dengan Aplikasi Firebase di lokasi berikut. Secara default, semua Aplikasi Firebase project Anda untuk platform yang sama (Apple vs Android vs Web) akan menggunakan kunci API yang sama.

  • Aplikasi Apple Firebase — Temukan kunci API yang dicocokkan secara otomatis di file konfigurasi Firebase, GoogleService-Info.plist, di kolom API_KEY.

  • Aplikasi Android Firebase — Temukan kunci API yang dicocokkan secara otomatis di file konfigurasi Firebase, google-services.json, di kolom current_key.

  • Aplikasi Web Firebase — Temukan kunci API yang dicocokkan secara otomatis di objek konfigurasi Firebase, di kolom apiKey.

Menggunakan kunci API

Kunci API digunakan untuk mengidentifikasi project Firebase Anda saat berinteraksi dengan layanan Firebase/Google. Secara khusus, kunci API digunakan untuk mengaitkan permintaan API dengan project Anda untuk kuota dan penagihan. Kunci API juga berguna untuk mengakses data publik.

Misalnya, Anda dapat menggunakan kunci API secara eksplisit dengan meneruskan nilainya ke dalam panggilan REST API sebagai parameter kueri. Contoh ini menunjukkan cara Anda dapat membuat permintaan ke API penyingkat link Dynamic Links:

POST https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY

Saat aplikasi Anda melakukan panggilan ke Firebase API yang memerlukan kunci API yang disediakan oleh klien seluler/web, aplikasi Anda akan otomatis mencari kunci API project dalam file/objek konfigurasi Firebase. Namun, Anda dapat menyediakan kunci API untuk aplikasi menggunakan mekanisme yang berbeda, termasuk variabel lingkungan.

Meninjau dan menerapkan batasan yang sesuai pada kunci API (direkomendasikan)

Meskipun tidak perlu merahasiakan kunci API untuk layanan Firebase, Anda harus meninjau dan menerapkan batasan dan pembatasan seperti yang dijelaskan di bagian ini.

Meninjau API yang otomatis ditambahkan ke daftar yang diizinkan untuk kunci Firebase API Anda

Saat Firebase membuat kunci API di project Anda, kami akan otomatis menambahkan "Pembatasan API" ke kunci tersebut. API yang ditambahkan ke daftar yang diizinkan ini adalah API terkait Firebase yang mengharuskan klien memberikan kunci API bersama dengan panggilan. Perhatikan bahwa sebagian besar API yang diperlukan untuk penggunaan layanan Firebase sebenarnya tidak perlu ada dalam daftar yang diizinkan untuk kunci API Anda.

Karena Firebase menambahkan API yang diperlukan untuk semua layanan Firebase, daftar yang diizinkan untuk kunci API dapat menyertakan API untuk produk yang tidak Anda gunakan. Anda dapat menghapus API dari daftar yang diizinkan, tetapi Anda harus sangat berhati-hati agar tidak menghapus API yang diperlukan untuk Firebase dan layanan Firebase yang Anda gunakan (lihat daftar API terkait Firebase yang perlu ada dalam daftar yang diizinkan untuk setiap layanan/produk). Jika tidak, Anda akan mendapatkan error saat melakukan panggilan ke layanan Firebase.

Memperketat kuota jika Anda menggunakan Authentication berbasis sandi

Jika Anda menggunakan Firebase Authentication berbasis sandi dan seseorang mendapatkan kunci API Anda, ia tidak akan dapat mengakses database project Firebase atau data Cloud Storage selama data ini dilindungi oleh Firebase Security Rules. Namun, mereka dapat menggunakan kunci API Anda untuk mengakses endpoint autentikasi Firebase dan membuat permintaan autentikasi terhadap project Anda.

Untuk mengurangi kemungkinan seseorang menyalahgunakan kunci API guna melancarkan serangan brute force, Anda dapat memperketat kuota default endpoint identitytoolkit.googleapis.com untuk mencerminkan ekspektasi traffic normal aplikasi Anda. Perlu diperhatikan bahwa jika Anda memperketat kuota ini dan aplikasi tiba-tiba mendapatkan pengguna baru, error login mungkin akan muncul hingga Anda meningkatkan kuota. Anda dapat mengubah kuota API project di Google Cloud console.

Menggunakan kunci API terpisah yang dibatasi untuk layanan non-Firebase

Meskipun kunci API yang digunakan untuk layanan Firebase umumnya tidak perlu dirahasiakan, Anda harus melakukan beberapa tindakan pencegahan tambahan pada kunci API yang Anda gunakan dengan API Google Cloud lainnya.

Jika Anda menggunakan Google Cloud API (di platform apa pun) yang bukan untuk layanan/produk Firebase, sebaiknya buat kunci API terpisah yang dibatasi untuk digunakan dengan API tersebut. Hal ini terutama penting jika API tersebut ditujukan untuk layanan Google Cloud yang dapat ditagih.

Misalnya, jika menggunakan Firebase ML dan Cloud Vision API di iOS, Anda harus membuat kunci API terpisah yang hanya digunakan untuk mengakses Cloud Vision API.

Dengan menggunakan kunci API terpisah yang dibatasi untuk API non-Firebase, Anda dapat merotasi atau mengganti kunci jika diperlukan dan menambahkan batasan tambahan pada kunci API tersebut tanpa mengganggu penggunaan layanan Firebase Anda.

Petunjuk berikut menjelaskan cara membuat kunci API terpisah yang dibatasi untuk API palsu yang disebut Super Service API.

Langkah 1: Mengonfigurasi kunci API yang ada untuk melarang akses ke Super Service API

  1. Buka halaman Credentials di Google Cloud console. Saat diminta, pilih project Anda.

  2. Untuk setiap kunci API yang ada dalam daftar, buka tampilan edit.

  3. Di bagian API restrictions, pilih Restrict key, lalu tambahkan ke daftar semua API yang ingin diakses oleh kunci API. Pastikan untuk tidak menyertakan API yang dituju oleh kunci API terpisah yang Anda buat (dalam contoh ini, Super Service API).

    Saat mengonfigurasi API restrictions untuk kunci API, Anda secara eksplisit mendeklarasikan API yang dapat diakses oleh kunci tersebut. Secara default, jika opsi Don't restrict key terpilih di bagian API restrictions, kunci API dapat digunakan untuk mengakses API apa pun yang diaktifkan untuk project.

Sekarang, kunci API yang ada tidak akan memberikan akses ke Super Service API, tetapi setiap kunci akan terus berfungsi untuk setiap API yang Anda tambahkan ke daftar API restrictions miliknya.

Langkah 2: Membuat dan menggunakan kunci API baru untuk akses ke Super Service API

  1. Kembali ke halaman Kredensial. Pastikan project Firebase Anda masih dipilih.

  2. Klik Buat kredensial > Kunci API. Catat kunci API baru ini, lalu klik Restrict key.

  3. Di bagian API restrictions, pilih Restrict key, lalu tambahkan hanya Super Service API ke daftar.

    Kunci API baru ini memberikan akses hanya ke Super Service API.

  4. Konfigurasi aplikasi dan layanan Anda agar menggunakan kunci API baru ini.

Menggunakan kunci API khusus lingkungan (disarankan)

Jika Anda menyiapkan project Firebase yang berbeda untuk lingkungan yang berbeda, seperti staging dan produksi, setiap instance aplikasi harus berinteraksi dengan project Firebase yang terkait. Misalnya, instance aplikasi staging tidak boleh berinteraksi dengan project Firebase produksi. Ini juga berarti bahwa aplikasi staging perlu menggunakan kunci API yang terkait dengan project Firebase staging.

Untuk mengurangi masalah saat mempromosikan perubahan kode mulai dari pengembangan hingga staging dan produksi, tetapkan kunci API sebagai variabel lingkungan atau sertakan dalam file konfigurasi, bukan memasukkan kunci API dalam kode itu sendiri.

Perhatikan bahwa jika ingin menggunakan Firebase Local Emulator Suite untuk pengembangan bersama dengan Firebase ML, Anda harus membuat dan menggunakan kunci API khusus debug. Petunjuk untuk membuat jenis kunci tersebut dapat ditemukan di dokumen Firebase ML.

FAQ dan pemecahan masalah

FAQ

Ya, secara default, semua kunci API yang disediakan secara otomatis oleh Firebase untuk digunakan dengan API terkait Firebase memiliki "Pembatasan API" yang diterapkan secara otomatis. Lihat daftar API terkait Firebase yang ada dalam daftar yang diizinkan ini.

API yang ditambahkan ke daftar yang diizinkan ini adalah API yang dipanggil oleh layanan Firebase dari kode klien dan memerlukan kunci API untuk identifikasi project atau aplikasi Firebase Anda. Perhatikan bahwa sebagian besar API yang diperlukan untuk penggunaan layanan Firebase sebenarnya tidak perlu ada dalam daftar yang diizinkan untuk kunci API Anda.

Karena Firebase menambahkan API yang diperlukan untuk semua layanan Firebase, daftar yang diizinkan untuk kunci API dapat menyertakan API untuk produk yang tidak Anda gunakan. Anda dapat menghapus API dari daftar yang diizinkan, tetapi Anda harus sangat berhati-hati agar tidak menghapus API yang diperlukan untuk Firebase dan layanan Firebase yang Anda gunakan (lihat daftar API terkait Firebase yang perlu ada dalam daftar yang diizinkan untuk setiap layanan/produk). Jika tidak, Anda akan mendapatkan error saat melakukan panggilan ke layanan Firebase.

Anda dapat melihat semua kunci API dan "Pembatasan API"-nya di panel APIs & Services > Credentials di Google Cloud console.

Perhatikan hal-hal berikut tentang cara Firebase menerapkan "Pembatasan API" ini:

  • Mulai Mei 2024, semua kunci API baru yang disediakan secara otomatis oleh Firebase akan otomatis dibatasi untuk daftar API terkait Firebase.

  • Selama Mei 2024, semua kunci API yang ada dan tidak dibatasi yang sebelumnya disediakan secara otomatis oleh Firebase akan dibatasi untuk daftar API terkait Firebase plus salah satu API project yang saat ini diaktifkan.

  • Semua kunci API yang ada dan sudah dibatasi yang sebelumnya disediakan secara otomatis oleh Firebase tidak akan diubah.

  • Kunci API yang ada yang tidak disediakan secara otomatis oleh Firebase tidak akan diubah.

Anda dapat menggunakan salah satu opsi berikut untuk menentukan kunci API mana yang terkait dengan Aplikasi Firebase Anda:

  1. Buka Project settings, lalu scroll ke bawah ke kartu Your apps.

  2. Pilih aplikasi yang diinginkan.

  3. Dapatkan file/objek konfigurasi Firebase untuk aplikasi yang diinginkan, lalu cari kunci API-nya:

    • Apple: Download GoogleService-Info.plist, lalu cari kolom API_KEY

    • Android: Download google-services.json, cari konfigurasi untuk aplikasi yang Anda inginkan (cari nama paketnya), lalu cari kolom current_key

    • Web: Pilih opsi Config, lalu cari kolom apiKey

  1. Dapatkan file/objek konfigurasi Firebase untuk aplikasi yang diinginkan dengan menjalankan perintah berikut:

    firebase apps:sdkconfig PLATFORM FIREBASE_APP_ID
    • PLATFORM (salah satu dari): IOS | ANDROID | WEB
    • FIREBASE_APP_ID: ID unik yang ditetapkan Firebase untuk Aplikasi Firebase Anda (cari ID Aplikasi Anda)
  2. Di konfigurasi Firebase cetak aplikasi, cari kunci API-nya:

    • Apple: Cari kolom API_KEY

    • Android: Cari konfigurasi untuk aplikasi yang diinginkan (cari nama paketnya), lalu cari kolom current_key

    • Web: Cari kolom apiKey

  1. Dapatkan apiKeyId (UID) kunci API dengan memanggil endpoint yang berlaku untuk aplikasi yang diinginkan, lalu teruskan nilai apiKeyId ke langkah berikutnya.

  2. Dapatkan string kunci API dengan memanggil projects.locations.keys.getKeyString.

    keyString ini adalah nilai yang sama yang dapat ditemukan di artefak konfigurasi Aplikasi (Apple | Android | Web).

  • Aplikasi Apple Firebase — Setiap aplikasi memiliki file konfigurasi sendiri dan hanya dapat mencantumkan satu kunci API.

  • Aplikasi Android Firebase — Semua aplikasi Android dalam project Firebase dicantumkan dalam file konfigurasi yang sama, dan setiap aplikasi hanya dapat mencantumkan satu kunci API. Namun, setiap aplikasi dalam file konfigurasi ini dapat mencantumkan kunci berbeda.

  • Aplikasi Web Firebase — Setiap aplikasi memiliki objek konfigurasinya sendiri dan hanya dapat mencantumkan satu kunci API.

Namun, Anda dapat menggunakan beberapa kunci API dengan satu aplikasi. Anda harus menyediakan mekanisme agar aplikasi dapat mengakses kunci API lainnya, seperti melalui variabel lingkungan. Mekanisme untuk mengakses kunci API lainnya tidak dapat bergantung hanya pada kunci API yang tercantum dalam file/objek konfigurasi Firebase tersebut.

Saat Anda pertama kali mendapatkan file/objek konfigurasi Firebase milik aplikasi, Firebase memeriksa apakah sudah ada kunci API di project yang memiliki "Pembatasan Aplikasi" yang cocok dengan aplikasi (misalnya, ID paket yang cocok untuk aplikasi Apple).

Jika Firebase tidak menemukan kunci yang dibatasi yang cocok, maka dalam file/objek konfigurasi akan tercantum iOS key untuk aplikasi Apple, Android key untuk aplikasi Android, dan Browser key untuk aplikasi web (dengan asumsi kunci ini ada dan tidak memiliki "Pembatasan Aplikasi" yang membuatnya tidak cocok dengan aplikasi tersebut).

Ya, Anda dapat menghapus kunci API secara manual dari file/objek konfigurasi. Namun, Anda harus memberikan beberapa mekanisme lain agar aplikasi dapat mengakses kunci API (seperti melalui variabel lingkungan). Jika tidak, panggilan ke layanan Firebase akan gagal.

Ya, Anda dapat mengedit file/objek konfigurasi secara manual untuk mengaitkan kunci API yang berbeda dengan aplikasi.

Perhatikan bahwa jika Anda mendapatkan kembali file/objek konfigurasi aplikasi dari konsol, file/objek tersebut akan selalu mencantumkan kunci API yang dicocokkan secara otomatis oleh Firebase dengan aplikasi tersebut. Jadi, Anda harus mengulang pengeditan manual sesuai kebutuhan.

Tidak, kunci API hanya mengidentifikasi project tertentu dan tidak dapat dipindahkan ke project lain.

Jika Anda menghapus kunci API yang digunakan oleh aplikasi, panggilan API dari aplikasi tersebut akan gagal. Anda mungkin akan mendapatkan laporan, email, atau error yang menyatakan bahwa Anda mencoba menggunakan kunci API yang tidak valid.

Penghapusan kunci API bersifat permanen dan tidak dapat diurungkan.

Untuk kunci Firebase API, satu-satunya API yang perlu ada dalam daftar yang diizinkan "Pembatasan API" kunci adalah API yang mengharuskan klien memberikan kunci API bersama dengan panggilan. Perhatikan bahwa sangat sedikit API terkait Firebase yang memiliki persyaratan ini. Sebagian besar API terkait Firebase yang diaktifkan di project Anda tidak perlu ada dalam daftar yang diizinkan "Pembatasan API" kunci.

Gunakan tabel berikut untuk menentukan API terkait Firebase mana yang perlu disertakan dalam daftar yang diizinkan "Pembatasan API" untuk kunci Firebase API. Ingat, kunci Firebase API hanya boleh digunakan untuk layanan Firebase. Pelajari lebih lanjut cara membuat kunci API terpisah yang dibatasi untuk jenis API tertentu.

Anda dapat melihat dan mengelola kunci API project Anda di panel APIs & Services > Credentials di Google Cloud console.

Nama API (nama layanan) Nama tampilan API
Layanan/produk Firebase terkait
firebase.googleapis.com Firebase Management API semua produk
logging.googleapis.com Cloud Logging API semua produk
firebaseinstallations.googleapis.com Firebase Installations API Cloud Messaging, Crashlytics, In-App Messaging, Performance Monitoring, Remote Config, Firebase ML
firebaseappcheck.googleapis.com Firebase App Check API App Check
firebaseappdistribution.googleapis.com Firebase App Distribution API App Distribution
firebaseapptesters.googleapis.com Firebase App Testers API App Distribution
identitytoolkit.googleapis.com Identity Toolkit API Authentication
securetoken.googleapis.com Token Service API Authentication
firebaserules.googleapis.com * Firebase Rules API Cloud Firestore, Cloud Storage, Realtime Database
datastore.googleapis.com Cloud Datastore API Cloud Firestore
firestore.googleapis.com Google Cloud Firestore API Cloud Firestore
fcmregistrations.googleapis.com FCM Registration API Cloud Messaging
firebasestorage.googleapis.com Cloud Storage for Firebase API Cloud Storage
firebasedynamiclinks.googleapis.com Firebase Dynamic Links API Dynamic Links
firebasehosting.googleapis.com * Firebase Hosting API Hosting
firebaseinappmessaging.googleapis.com Firebase In-App Messaging API In-App Messaging
firebaseml.googleapis.com Firebase ML API Firebase ML
mlkit.googleapis.com ** ML Kit API Firebase ML
mobilecrashreporting.googleapis.com Mobile Crash Reporting API Performance Monitoring
play.googleapis.com Google Play Android Developer API Performance Monitoring
firebaseremoteconfig.googleapis.com Firebase Remote Config API Performance Monitoring, Remote Config
firebaseremoteconfigrealtime.googleapis.com Firebase Remote Config Realtime API Performance Monitoring, Remote Config
cloudconfig.googleapis.com ** T/A Remote Config
firebasedatabase.googleapis.com * Firebase Realtime Database API Realtime Database
firebasevertexai.googleapis.com Vertex AI in Firebase API Vertex AI in Firebase

* Hanya diperlukan jika Anda menggunakan kunci Firebase API dengan alat pihak ketiga atau akses REST langsung ke layanan/produk Firebase.

** Diperlukan untuk SDK produk versi sebelumnya. Jika Anda menggunakan SDK versi terbaru, API tidak perlu berada dalam daftar yang diizinkan kunci.

Pemecahan masalah

Ikuti panduan dalam FAQ ini jika Anda mendapatkan error API_KEY_SERVICE_BLOCKED atau error yang terlihat seperti berikut:

Forbidden: 403 POST https://example-service.googleapis.com/method: Requests to this API example-service.googleapis.com method google.example-service.rest.method are blocked.

Kunci API yang digunakan oleh aplikasi Anda untuk memanggil API mungkin memiliki "Pembatasan API" yang diterapkan padanya, dan daftar yang diizinkan kunci tidak menyertakan API tersebut.

Mungkin "Pembatasan API" telah diterapkan pada kunci API yang digunakan oleh aplikasi web Anda. Jika demikian, pastikan bahwa Firebase Management API ada dalam daftar API yang diizinkan.

Berikut adalah beberapa penyebab paling umum untuk kunci API yang tidak valid:

  • Kunci API memiliki "Pembatasan Kunci API" yang diterapkan padanya, yang membuatnya tidak dapat cocok dengan aplikasi yang mencoba menggunakan kunci tersebut ("Pembatasan Aplikasi") atau tidak dapat digunakan untuk API yang sedang dipanggil ("Pembatasan API").

  • Kunci API telah dihapus dari project di Google Cloud console.

  • Kunci API tidak dibuat untuk Project ID yang tercantum di file/objek konfigurasi Firebase milik aplikasi.

Salah satu cara untuk memperbaiki masalah ini adalah dengan mendapatkan versi terbaru file/objek konfigurasi Firebase milik aplikasi, lalu mengganti file/objek konfigurasi lama dengan file/objek yang telah diperbarui. Sebelum mengirim file konfigurasi untuk download atau menampilkan objek konfigurasi di konsol, Firebase akan memeriksa apakah kunci API yang tercantum cocok dengan aplikasi.