[proxy] firebase.google.com — ← back | site home | direct (HTTPS) ↗ | proxy home | ◑ dark◐ light

Add the Firebase Admin SDK to your server

The Admin SDK is a set of server libraries that lets you interact with Firebase from privileged environments to perform actions like:

If you are interested in using the Node.js SDK as a client for end-user access (for example, in a Node.js desktop or IoT application), as opposed to admin access from a privileged environment (like a server), you should instead follow the instructions for setting up the client JavaScript SDK.

Here is a feature matrix showing what Firebase features are supported in each language:

Feature Node.js Java Python Go C#
Custom Token Minting
ID Token Verification
User Management
Control Access With Custom Claims
Refresh Token Revocation
Import Users
Session Cookie Management
Generating Email Action Links
Managing SAML/OIDC provider configurations
Multi-tenancy support
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
FCM Multicast
Manage FCM Topic Subscriptions
Cloud Storage
Cloud Firestore
Enqueue functions with Cloud Tasks
Project Management
Security Rules
ML Model Management
Firebase Remote Config
Firebase App Check
Firebase Extensions

To learn more about Admin SDK integration for these uses, see the corresponding Realtime Database, FCM, Authentication, Remote Config, and Cloud Storage documentation. The rest of this page focuses on basic setup for the Admin SDK.

Prerequisites

Set up a Firebase project and service account

To use the Firebase Admin SDK, you'll need the following:

If you don't already have a Firebase project, you need to create one in the Firebase console. Visit Understand Firebase Projects to learn more about Firebase projects.

Create a Firebase project

New to Firebase or Cloud

Follow these steps if you're new to Firebase or Google Cloud.
You can also follow these steps if you want to create a wholly new Firebase project (and its underlying Google Cloud project).

  1. Sign into the Firebase console.
  2. Click the button to create a new Firebase project.

  3. In the text field, enter a project name.

    If you're part of a Google Cloud org, you can optionally select which folder you create your project in.

  4. If prompted, review and accept the Firebase terms, then click Continue.
  5. (Optional) Enable AI assistance in the Firebase console (called "Gemini in Firebase"), which can help you get started and streamline your development process.

  6. (Optional) Set up Google Analytics for your project, which enables an optimal experience using these Firebase products: Firebase A/B Testing, Cloud Messaging, Crashlytics, In-App Messaging, and Remote Config (including Personalization).

    Either select an existing Google Analytics account or create a new account. If you create a new account, select your Analytics reporting location, then accept the data sharing settings and Google Analytics terms for your project.

  7. Click Create project.

Firebase creates your project, provisions some initial resources, and enables important APIs. When the process completes, you'll be taken to the overview page for your Firebase project in the Firebase console.

Existing Cloud project

Follow these steps if you want to start using Firebase with an existing Google Cloud project. Learn more about and troubleshoot "adding Firebase" to an existing Google Cloud project.

  1. Sign into the Firebase console with the account that gives you access to the existing Google Cloud project.
  2. Click the button to create a new Firebase project.
  3. At the bottom of the page, click Add Firebase to Google Cloud project.
  4. In the text field, start entering the project name of the existing project, and then select the project from the displayed list.
  5. Click Open project.
  6. If prompted, review and accept the Firebase terms, then click Continue.
  7. (Optional) Enable AI assistance in the Firebase console (called "Gemini in Firebase"), which can help you get started and streamline your development process.

  8. (Optional) Set up Google Analytics for your project, which enables an optimal experience using these Firebase products: Firebase A/B Testing, Cloud Messaging, Crashlytics, In-App Messaging, and Remote Config (including Personalization).

    Either select an existing Google Analytics account or create a new account. If you create a new account, select your Analytics reporting location, then accept the data sharing settings and Google Analytics terms for your project.

  9. Click Add Firebase.

Firebase adds Firebase to your existing project. When the process completes, you'll be taken to the overview page for your Firebase project in the Firebase console.

If you are setting up a new project, you need to install the SDK for the language of your choice.

Node.js

The Firebase Admin Node.js SDK is available on npm. If you don't already have a package.json file, create one via npm init. Next, install the firebase-admin npm package and save it to your package.json:

npm install firebase-admin --save

To use the module in your application, require it from any JavaScript file:

const { initializeApp } = require('firebase-admin/app');

If you are using ES2015, you can import the module:

import { initializeApp } from 'firebase-admin/app';

Java

The Firebase Admin Java SDK is published to the Maven central repository. To install the library, declare it as a dependency in your build.gradle file:

dependencies {
  implementation 'com.google.firebase:firebase-admin:9.8.0'
}

If you use Maven to build your application, you can add the following dependency to your pom.xml:

<dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.8.0</version>
</dependency>

Python

The Firebase Admin Python SDK is available via pip. You can install the library for all users via sudo:

sudo pip install firebase-admin

Or, you can install the library for just the current user by passing the --user flag:

pip install --user firebase-admin

Go

The Go Admin SDK can be installed using the go get utility:

# Install the latest version:
go get firebase.google.com/go/v4@latest

# Or install a specific version:
go get firebase.google.com/go/v4@4.19.0

C#

The .NET Admin SDK can be installed using the .NET package manager:

Install-Package FirebaseAdmin -Version 3.4.0

Alternatively, install it using the dotnet command-line utility:

dotnet add package FirebaseAdmin --version 3.4.0

Or, you can install it by adding the following package reference entry to your .csproj file:

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.4.0" />
</ItemGroup>

Initialize the SDK

Once you have created a Firebase project, you can initialize the SDK with Google Application Default Credentials. Because default credentials lookup is fully automated in Google environments, with no need to supply environment variables or other configuration, this way of initializing the SDK is strongly recommended for applications running in Google environments such as Firebase App Hosting, Cloud Run, App Engine, and Cloud Functions for Firebase.

To optionally specify initialization options for services such as Realtime Database, Cloud Storage, or Cloud Functions, use the FIREBASE_CONFIG environment variable. If the content of the FIREBASE_CONFIG variable begins with a { it will be parsed as a JSON object. Otherwise the SDK assumes that the string is the path of a JSON file containing the options.

Node.js

const app = initializeApp();

Java

FirebaseApp.initializeApp();

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create();

Once it is initialized, you can use the Admin SDK to accomplish the following types of tasks:

Using an OAuth 2.0 refresh token

The Admin SDK also provides a credential which allows you to authenticate with a Google OAuth2 refresh token:

Node.js

const myRefreshToken = '...'; // Get refresh token from OAuth2 flow

initializeApp({
  credential: refreshToken(myRefreshToken),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FileInputStream refreshToken = new FileInputStream("path/to/refreshToken.json");

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.fromStream(refreshToken))
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

cred = credentials.RefreshToken('path/to/refreshToken.json')
default_app = firebase_admin.initialize_app(cred)

Go

opt := option.WithCredentialsFile("path/to/refreshToken.json")
config := &firebase.Config{ProjectID: "my-project-id"}
app, err := firebase.NewApp(context.Background(), config, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.FromFile("path/to/refreshToken.json"),
});

Initialize the SDK in non-Google environments

If you are working in a non-Google server environment in which default credentials lookup can't be fully automated, you can initialize the SDK with an exported service account key file.

Firebase projects support Google service accounts, which you can use to call Firebase server APIs from your app server or trusted environment. If you're developing code locally or deploying your application on-premises, you can use credentials obtained via this service account to authorize server requests.

To authenticate a service account and authorize it to access Firebase services, you must generate a private key file in JSON format.

To generate a private key file for your service account:

  1. In the Firebase console, open Settings > Service Accounts.

  2. Click Generate New Private Key, then confirm by clicking Generate Key.

  3. Securely store the JSON file containing the key.

When authorizing via a service account, you have two choices for providing the credentials to your application. You can either set the GOOGLE_APPLICATION_CREDENTIALS environment variable, or you can explicitly pass the path to the service account key in code. The first option is more secure and is strongly recommended.

To set the environment variable:

Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the file path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

Linux or macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

With PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

After you've completed the above steps, Application Default Credentials (ADC) is able to implicitly determine your credentials, allowing you to use service account credentials when testing or running in non-Google environments.

Initialize the SDK as shown:

Node.js

initializeApp({
    credential: applicationDefault(),
    databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "my-project-id",
});

Initialize multiple apps

In most cases, you only have to initialize a single, default app. You can access services off of that app in two equivalent ways:

Node.js

// Initialize the default app
const defaultApp = initializeApp(defaultAppConfig);

console.log(defaultApp.name);  // '[DEFAULT]'

// Retrieve services via the defaultApp variable...
let defaultAuth = getAuth(defaultApp);
let defaultDatabase = getDatabase(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = getAuth();
defaultDatabase = getDatabase();

Java

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

System.out.println(defaultApp.getName());  // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
FirebaseAuth defaultAuth = FirebaseAuth.getInstance(defaultApp);
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.getInstance();
defaultDatabase = FirebaseDatabase.getInstance();

Python

# Import the Firebase service
from firebase_admin import auth

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)
print(default_app.name)  # "[DEFAULT]"

# Retrieve services via the auth package...
# auth.create_custom_token(...)

Go

// Initialize default app
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access auth service from the default app
client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

C#

// Initialize the default app
var defaultApp = FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});
Console.WriteLine(defaultApp.Name); // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
var defaultAuth = FirebaseAuth.GetAuth(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.DefaultInstance;

Some use cases require you to create multiple apps at the same time. For example, you might want to read data from the Realtime Database of one Firebase project and mint custom tokens for another project. Or you might want to authenticate two apps with separate credentials. The Firebase SDK allows you create multiple apps at the same time, each with their own configuration information.

Node.js

// Initialize the default app
initializeApp(defaultAppConfig);

// Initialize another app with a different config
var otherApp = initializeApp(otherAppConfig, 'other');

console.log(getApp().name);  // '[DEFAULT]'
console.log(otherApp.name);     // 'other'

// Use the shorthand notation to retrieve the default app's services
const defaultAuth = getAuth();
const defaultDatabase = getDatabase();

// Use the otherApp variable to retrieve the other app's services
const otherAuth = getAuth(otherApp);
const otherDatabase = getDatabase(otherApp);

Java

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

// Initialize another app with a different config
FirebaseApp otherApp = FirebaseApp.initializeApp(otherAppConfig, "other");

System.out.println(defaultApp.getName());  // "[DEFAULT]"
System.out.println(otherApp.getName());    // "other"

// Use the shorthand notation to retrieve the default app's services
FirebaseAuth defaultAuth = FirebaseAuth.getInstance();
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance();

// Use the otherApp variable to retrieve the other app's services
FirebaseAuth otherAuth = FirebaseAuth.getInstance(otherApp);
FirebaseDatabase otherDatabase = FirebaseDatabase.getInstance(otherApp);

Python

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)

#  Initialize another app with a different config
other_app = firebase_admin.initialize_app(cred, name='other')

print(default_app.name)    # "[DEFAULT]"
print(other_app.name)      # "other"

# Retrieve default services via the auth package...
# auth.create_custom_token(...)

# Use the `app` argument to retrieve the other app's services
# auth.create_custom_token(..., app=other_app)

Go

// Initialize the default app
defaultApp, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Initialize another app with a different config
opt := option.WithCredentialsFile("service-account-other.json")
otherApp, err := firebase.NewApp(context.Background(), nil, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access Auth service from default app
defaultClient, err := defaultApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

// Access auth service from other app
otherClient, err := otherApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

C#

// Initialize the default app
var defaultApp = FirebaseApp.Create(defaultOptions);

// Initialize another app with a different config
var otherApp = FirebaseApp.Create(otherAppConfig, "other");

Console.WriteLine(defaultApp.Name); // "[DEFAULT]"
Console.WriteLine(otherApp.Name); // "other"

// Use the shorthand notation to retrieve the default app's services
var defaultAuth = FirebaseAuth.DefaultInstance;

// Use the otherApp variable to retrieve the other app's services
var otherAuth = FirebaseAuth.GetAuth(otherApp);

Set scopes for Realtime Database and Authentication

If you're using a Google Compute Engine VM with Google Application Default Credentials for Realtime Database or Authentication, make sure to also set the right access scopes. For Realtime Database and Authentication, you need scopes ending in userinfo.email and either cloud-platform or firebase.database. To check the existing access scopes and change them, run the following commands using gcloud.

gcloud

# Check the existing access scopes
gcloud compute instances describe [INSTANCE_NAME] --format json

# The above command returns the service account information. For example:
  "serviceAccounts": [
   {
    "email": "your.gserviceaccount.com",
    "scopes": [
     "https://www.googleapis.com/auth/cloud-platform",
     "https://www.googleapis.com/auth/userinfo.email"
     ]
    }
  ],

# Stop the VM, then run the following command, using the service account
# that gcloud returned when you checked the scopes.

gcloud compute instances set-service-account [INSTANCE_NAME] --service-account "your.gserviceaccount.com" --scopes "https://www.googleapis.com/auth/firebase.database,https://www.googleapis.com/auth/userinfo.email"

Testing with gcloud end user credentials

When testing the Admin SDK locally with Google Application Default Credentials obtained by running gcloud auth application-default login, additional changes are needed to use Firebase Authentication due to the following:

As a workaround, you can generate Google Application Default Credentials in gcloud using your own OAuth 2.0 client ID. The OAuth client ID has to be a Desktop app application type.

gcloud

gcloud auth application-default login --client-id-file=[/path/to/client/id/file]

You can specify the project ID explicitly on app initialization or just use the GOOGLE_CLOUD_PROJECT environment variable. The latter avoids the need to make any additional changes to test your code.

To explicitly specify the project ID:

Node.js

import { initializeApp, applicationDefault } from 'firebase-admin/app';

initializeApp({
  credential: applicationDefault(),
  projectId: '<FIREBASE_PROJECT_ID>',
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setProjectId("<FIREBASE_PROJECT_ID>")
    .build();

FirebaseApp.initializeApp(options);

Python

app_options = {'projectId': '<FIREBASE_PROJECT_ID>'}
default_app = firebase_admin.initialize_app(options=app_options)

Go

config := &firebase.Config{ProjectID: "<FIREBASE_PROJECT_ID>"}
app, err := firebase.NewApp(context.Background(), config)
if err != nil {
        log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "<FIREBASE_PROJECT_ID>",
});

Next steps

Learn about Firebase:

Add Firebase features to your app: