Understand Firebase projects

Note: If you're using the Firebase Management REST API to programmatically create a Firebase project, you must first create a Google Cloud project, then add Firebase services to the existing project.Note: The project number and the project ID are the truly unique identifiers for a project across all of Firebase and Google Cloud.After Firebase provisions resources for a Firebase project, you cannot change its project ID. To use a specific identifier for Firebase resources, you must edit the project ID during the initial creation of the project.Caution: We do not recommend manually modifying an app's Firebase config file or object. If you initialize an app with invalid or missing values for any of these required "Firebase options", then your end users may experience serious issues.Note: For each Android app, if you provide a SHA-1 key for the app, you need to provide a package name and SHA-1 key combination that is globally unique across all of Google Cloud.

This page offers brief overviews of several important concepts about Firebase projects. When available, follow the links to find more detailed information about features, services, and even other platforms. At the bottom of this page, find a listing of general best practices for Firebase projects.

Relationship between Firebase projects, apps, and products

A Firebase project is the top-level entity for Firebase. In a project, you create Firebase apps by registering your iOS, Android, or web apps. After you register your apps with Firebase, you can add the Firebase SDKs for any number of Firebase products, like Analytics, Cloud Firestore, Performance Monitoring, or Remote Config.

Learn more detailed information about this process in the Getting Started guides (iOS | Android | web | Unity | C++).

Relationship between Firebase projects and Google Cloud

When you create a new Firebase project in the Firebase console, you're actually creating a Google Cloud project behind the scenes. You can think of a Google Cloud project as a virtual container for data, code, configuration, and services. A Firebase project is a Google Cloud project that has additional Firebase-specific configurations and services. You can even create a Google Cloud project first, then add Firebase to the project later.

Since a Firebase project is a Google Cloud project:

Setting up a Firebase project and registering apps

You can set up a Firebase project and register apps in the Firebase console (or, for advanced use cases, via the Firebase Management REST API or the Firebase CLI). When you set up a project and register apps, you need to make some organizational decisions and add Firebase-specific configuration information to your local projects.

Make sure to review some general project-level best practices (at the bottom of this page) before setting up a project and registering apps.

The project name

When you create a project, you provide a project name. This identifier is the internal-only name for a project in the Firebase console, the Google Cloud Console, and the Firebase CLI. The project name is not exposed in any publicly visible Firebase or Google Cloud product, service, or resource; it simply serves to help you more easily distinguish among multiple projects.

You can edit a project name at any time in the settings Project settings of the Firebase console. The project name is displayed in the top pane.

The project number

A Firebase project (and its associated Google Cloud project) has a project number. This is the Google-assigned globally unique canonical identifier for the project. Use this identifier when configuring integrations and/or making API calls to Firebase, Google, or third-party services.

API calls and the project number

For many API calls, you need to include a unique identifier for a project. Although many APIs accept the project ID, it's recommended that you use the project number for making API calls to Firebase, Google, or third-party services.

Learn more about using project identifiers, especially the project number, in Google's AIP 2510 standard.

Find the project number

  • Firebase console: Click settings Project settings. The project number is displayed in the top pane.
  • Firebase CLI: Run firebase projects:list. The project number is displayed along with all the Firebase projects associated with your account.
  • Firebase Management REST API: Call projects.list. The response body contains the project number in the FirebaseProject object.

The project ID

A Firebase project (and its associated Google Cloud project) has a project ID. This is a user-defined unique identifier for the project across all of Firebase and Google Cloud. When you create a Firebase project, Firebase automatically assigns a unique ID to the project, but you can edit it during project setup. This identifier should generally be treated as a convenience alias to reference the project.

If you delete a project, the project ID is also deleted and can never be used again by any other project.

Firebase resources and the project ID

The project ID displays in publicly visible Firebase resources, for example:

  • Default Hosting subdomain — PROJECT_ID.web.app and PROJECT_ID.firebaseapp.com
  • Default Realtime Database URL — PROJECT_ID-default-rtdb.firebaseio.com or PROJECT_ID-default-rtdb.REGION_CODE.firebasedatabase.app
  • Default Cloud Storage bucket name — PROJECT_ID.appspot.com

For all of the aforementioned resources, you can create non-default instances. The publicly visible names of non-defaults are fully-customizable. You can connect custom domains to a Firebase-hosted site, shard the Realtime Database, and create multiple Cloud Storage buckets (visit the platform-specific Get Started page).

The Firebase CLI and the project ID

For some use cases, you might have multiple Firebase projects associated with the same local app directory. In these situations, when you use the Firebase CLI, you need to pass the --project flag with the firebase commands to communicate which Firebase project you want to interact with.

You can also set up a project alias for each Firebase project so that you don't have to remember project IDs.

API calls and the project ID

For many API calls, you need to include a unique identifier for a project. Although many APIs accept the project ID, it's recommended that you use the project number for making API calls to Firebase, Google, or third-party services.

Learn more about using project identifiers, especially the project number, in Google's AIP 2510 standard.

Find the project ID

  • Firebase console: Click settings Project settings. The project ID is displayed in the top pane.
  • Firebase CLI: Run firebase projects:list. The project ID is displayed along with all the Firebase projects associated with your account.
  • Firebase Management REST API: Call projects.list. The response body contains the project ID in the FirebaseProject object.

Firebase config files and objects

When you register an app with a Firebase project, the Firebase console provides a Firebase configuration file (iOS/Android apps) or a configuration object (web apps) that you add directly to your local app directory.

  • For iOS apps, you add a GoogleService-Info.plist configuration file.
  • For Android apps, you add a google-services.json configuration file.
  • For web apps, you add a Firebase configuration object.

At any time, you can obtain an app's Firebase config file or object.

A Firebase config file or object associates an app with a specific Firebase project and its resources (databases, storage buckets, etc.). The configuration includes "Firebase options", which are parameters required by Firebase and Google services to communicate with Firebase server APIs and to associate client data with the Firebase project and Firebase app. Here are the required, minimum "Firebase options":

  • API key: a simple encrypted string used when calling certain APIs that don't need to access private user data (example value: AIzaSyDOCAbC123dEf456GhI789jKl012-MnO)
  • Project ID: a user-defined unique identifier for the project across all of Firebase and Google Cloud. This identifier may appear in URLs or names for some Firebase resources, but it should generally be treated as a convenience alias to reference the project. (example value: myapp-project-123)

  • Application ID ("AppID"): the unique identifier for the Firebase app across all of Firebase with a platform-specific format:

    • Firebase iOS apps: GOOGLEAPPID (example value: 1:1234567890:ios:321abc456def7890) This is not an Apple bundle ID.
    • Firebase Android apps: mobilesdkappid (example value: 1:1234567890:android:321abc456def7890) This is not an Android package name or Android application ID.
    • Firebase Web apps: appId (example value: 1:65211879909:web:3ae38ef1cdcb2e01fe5f0c)

The content of the Firebase config file or object is considered public, including the app's platform-specific ID (iOS bundle ID or Android package name) and the Firebase project-specific values, like the API Key, project ID, Realtime Database URL, and Cloud Storage bucket name. Given this, use Firebase Security Rules to protect your data and files in Realtime Database, Cloud Firestore, and Cloud Storage.

For open source projects, we generally do not recommend including the app's Firebase config file or object in source control because, in most cases, your users should create their own Firebase projects and point their apps to their own Firebase resources (via their own Firebase config file or object).

Managing a Firebase project

Make sure to review the general project-level best practices (at the bottom of this page) for considerations that might affect how you manage a Firebase project.

Tools to manage a project

Firebase console

The Firebase console offers the richest environment for managing Firebase products, apps, and project-level settings.

The left-side panel of the console lists the Firebase products, organized by top-level categories. At the top of the left-side panel, access a project's settings by clicking settings. A project's settings include integrations, access permissions, and billing.

The middle of the console displays buttons that launch setup workflows to register various types of apps. After you start using Firebase, the main area of the console changes into a dashboard that displays stats on the products you use.

Firebase CLI (a command line tool)

Firebase also offers the Firebase CLI for configuring and managing specific Firebase products, like Firebase Hosting and Cloud Functions for Firebase.

After installing the CLI, you have access to the global firebase command. Use the CLI to link your local app directory to a Firebase project, then deploy new versions of Firebase-hosted content or updates to functions.

Firebase Management REST API

Using the Firebase Management REST API, you can programmatically manage a Firebase project. For example, you can programmatically register an app with a project or list the apps that are already registered (iOS | Android | web).

General best practices

Adding apps to a project

Ensure that all apps within a project are platform variants of the same application from an end-user perspective. It's advisable to register the iOS, Android, and web versions of the same app or game with the same Firebase project. All the apps in a project generally share the same Firebase resources (database, storage buckets, etc.).

If you have multiple build variants with different iOS bundle IDs or Android package names defined, you can register each variant with a separate Firebase project. However, if you have variants that share the same Firebase resources, register them with the same Firebase project.

Here are some general limits for Firebase projects, apps, and sites:

  • Number of projects per account

    • Spark pricing plan — Project-creation quota is limited to a lower count of projects (usually around 5-10).
    • Blaze pricing plan — Project-creation quota per account increases substantially as long as the associated Cloud Billing account is in good standing.

    The limit on project-creation quota is rarely a concern for most developers, but if needed, you can request an increase in project quota.

    Be aware that the complete deletion of a project requires 30 days and counts toward project quota until the project is fully deleted.

  • Number of apps per project

    Firebase restricts the total number of Firebase Apps within a Firebase project to 30.

    You should ensure that all Firebase Apps within a single Firebase project are platform variants of the same application from an end-user perspective. Read more about best practices for multi-tenancy below.

    Learn more about the limit on apps per project in the FAQ.

  • Number of Hosting sites per project

    The Firebase Hosting multisite feature supports a maximum of 36 sites per project.

Multi-tenancy

Connecting several different logically independent apps and/or web sites to a single Firebase project (often called "multi-tenancy") is not recommended. Multi-tenancy can lead to serious configuration and data privacy concerns problems, including unintended issues with analytics aggregation, shared authentication, overly-complex database structures, and difficulties with security rules.

Generally, if a set of apps don't share the same data and configurations, strongly consider registering each app with a different Firebase project.

For example, if you develop a white label application, each independently labelled app should have its own Firebase project, but the iOS and Android versions of that label can be in the same project. Each independently labeled app shouldn't (for privacy reasons) share data with the others.

Launching your app