Connecting a project

Step-by-step — how to create a Firebase service account, what permissions it needs, and how Firepanel verifies the connection.

Firepanel connects to your Firebase project using a service account — a Google-issued credential that lets the Firebase Admin SDK act on your project. This page walks through getting one and connecting it, and explains exactly what happens to it afterward.

What is a service account?#

A service account is a special Google account that belongs to your Firebase project rather than to a person. Firebase can generate a private key for it as a JSON file. That JSON is what Firepanel uses to read and write your data on your behalf.

Warning

A service account key grants administrative access to your project. Treat the JSON file like a password — don't commit it to git, paste it into chat, or email it around. Once it's in Firepanel it's encrypted at rest, and you can revoke it from Firebase at any time.

Step 1 — Get a service account key from Firebase#

Open the Firebase Console

Go to console.firebase.google.com and select the project you want to connect.

Open Project settings

Click the gear icon next to "Project Overview" in the top-left, then choose Project settings.

Go to the Service accounts tab

In Project settings, switch to the Service accounts tab. You'll see the Firebase Admin SDK panel.

Generate a new private key

Click Generate new private key, then confirm in the dialog. Your browser downloads a .json file. This is your service account key — keep it somewhere safe for the next step.

The downloaded file looks roughly like this:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "…",
  "private_key": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk-xxxxx@your-project-id.iam.gserviceaccount.com",
  "client_id": "…"
}

Step 2 — Paste it into Firepanel#

Start the connect wizard

In Firepanel, open your projects page and click Connect a project. The wizard opens on a short instructions screen — click Next when you have your key ready.

Provide the JSON

Either drag the .json file onto the drop zone or paste its contents into the text box. Firepanel never stores the raw JSON — it's encrypted with AES-256-GCM before it touches our database.

Validate & continue

Click Validate & continue. Firepanel parses the JSON, confirms it's a real service account, and runs a connection check (see below). If anything's wrong, you get a clear, specific error and stay on this step.

Name and confirm

On the confirm screen, Firepanel shows the detected project ID, the service account email, and which Firebase products it could reach. Give the project a nickname (only visible to you and your team) and click Connect project.

What permissions does it need?#

The key generated by the Firebase Admin SDK panel comes with the Editor / Firebase Admin SDK Administrator Service Agent role by default, which is enough for everything Firepanel does today:

Capability	Why Firepanel needs it
Read Firestore	Browse collections and documents
Write Firestore	Inline edits, creating and deleting documents, bulk operations
Reach Auth & Storage	Connection health checks (full Auth/Storage management is coming soon)

You don't need to configure IAM roles by hand — the default key works. For a deeper look at scopes and least-privilege setups, see Permissions.

How connection verification works#

When you click Validate & continue, Firepanel does two things:

Validates the JSON. It checks that the file is valid JSON and contains the required service-account fields (type, project_id, private_key, client_email). A missing or malformed field produces a precise error instead of a silent failure.
Probes your project. Using the key, Firepanel makes lightweight calls to Firestore, Auth, and Storage to confirm the credential actually works and to see which products are reachable. The confirm screen shows a green or red badge for each.

A red badge isn't always fatal — for example, Storage may be unreachable simply because a default bucket hasn't been created. Firestore is the one that matters for today's features.

Note

Already connected this project? Firepanel detects duplicate project_ids and will tell you rather than connecting it twice. To re-connect with a fresh key, disconnect the existing one first from the project's settings.

After you connect#

Your encrypted credentials live in our database; the plaintext key is only ever decrypted in memory, for the duration of a single request, and is never sent to your browser. Disconnecting a project permanently deletes its stored credentials. The full lifecycle is described in How Firepanel works and Data security.

If the connection check failed, jump to Troubleshooting.