With the Admin SDK, you can read and write Realtime Database data with full admin privileges, or with finer-grained limited privileges. In this document, we'll guide you through adding the Firebase Admin SDK to your project for accessing the Firebase Realtime Database.
Admin SDK Setup
To get started with the Firebase Realtime Database on your server, you'll first need to set up the Firebase Admin SDK in your language of choice.
Admin SDK Authentication
Before you can access the Firebase Realtime Database from a server using the Firebase Admin SDK, you must authenticate your server with Firebase. When you authenticate a server, rather than sign in with a user account's credentials as you would in a client app, you authenticate with a service account which identifies your server to Firebase.
You can get two different levels of access when you authenticate using the Firebase Admin SDK:
| Firebase Admin SDK Auth Access Levels | |
|---|---|
| Administrative privileges | Complete read and write access to a project's Realtime Database. Use with caution to complete administrative tasks such as data migration or restructuring that require unrestricted access to your project's resources. |
| Limited privileges | Access to a project's Realtime Database, limited to only the resources your server needs. Use this level to complete administrative tasks that have well-defined access requirements. For example, when running a summarization job that reads data across the entire database, you can protect against accidental writes by setting a read-only security rule and then initializing the Admin SDK with privileges limited by that rule. |
Authenticate with admin privileges
When you initialize the Firebase Admin SDK with the credentials for a service account with the Editor role on your Firebase project, that instance has complete read and write access to your project's Realtime Database.
Java
// Fetch the service account key JSON file contentsFileInputStreamserviceAccount=newFileInputStream("path/to/serviceAccount.json");// Initialize the app with a service account, granting admin privilegesFirebaseOptionsoptions=FirebaseOptions.builder().setCredentials(GoogleCredentials.fromStream(serviceAccount))// The database URL depends on the location of the database.setDatabaseUrl("https://DATABASE_NAME.firebaseio.com").build();FirebaseApp.initializeApp(options);// As an admin, the app has access to read and write all data, regardless of Security RulesDatabaseReferenceref=FirebaseDatabase.getInstance().getReference("restricted_access/secret_document");ref.addListenerForSingleValueEvent(newValueEventListener(){@OverridepublicvoidonDataChange(DataSnapshotdataSnapshot){Objectdocument=dataSnapshot.getValue();System.out.println(document);}@OverridepublicvoidonCancelled(DatabaseErrorerror){}});
Node.js
varadmin=require("firebase-admin");// Fetch the service account key JSON file contentsvarserviceAccount=require("path/to/serviceAccountKey.json");// Initialize the app with a service account, granting admin privilegesadmin.initializeApp({credential:admin.credential.cert(serviceAccount),// The database URL depends on the location of the databasedatabaseURL:"https://DATABASE_NAME.firebaseio.com"});// As an admin, the app has access to read and write all data, regardless of Security Rulesvardb=admin.database();varref=db.ref("restricted_access/secret_document");ref.once("value",function(snapshot){console.log(snapshot.val());});
Python
importfirebase_adminfromfirebase_adminimportcredentialsfromfirebase_adminimportdb# Fetch the service account key JSON file contentscred=credentials.Certificate('path/to/serviceAccountKey.json')# Initialize the app with a service account, granting admin privilegesfirebase_admin.initialize_app(cred,{'databaseURL':'https://databaseName.firebaseio.com'})# As an admin, the app has access to read and write all data, regradless of Security Rulesref=db.reference('restricted_access/secret_document')print(ref.get())
Go
ctx:=context.Background()conf:=&firebase.Config{DatabaseURL:"https://databaseName.firebaseio.com",}// Fetch the service account key JSON file contentsopt:=option.WithCredentialsFile("path/to/serviceAccountKey.json")// Initialize the app with a service account, granting admin privilegesapp,err:=firebase.NewApp(ctx,conf,opt)iferr!=nil{log.Fatalln("Error initializing app:",err)}client,err:=app.Database(ctx)iferr!=nil{log.Fatalln("Error initializing database client:",err)}// As an admin, the app has access to read and write all data, regradless of Security Rulesref:=client.NewRef("restricted_access/secret_document")vardatamap[string]interface{}iferr:=ref.Get(ctx,&data);err!=nil{log.Fatalln("Error reading from database:",err)}fmt.Println(data)
Authenticate with limited privileges
As a best practice, a service should have access to only the resources it needs. To get more fine-grained control over the resources a Firebase app instance can access, use a unique identifier in your Security Rules to represent your service. Then set up appropriate rules which grant your service access to the resources it needs. For example:
{ "rules": { "public_resource": { ".read": true, ".write": true }, "some_resource": { ".read": "auth.uid === 'my-service-worker'", ".write": false }, "another_resource": { ".read": "auth.uid === 'my-service-worker'", ".write": "auth.uid === 'my-service-worker'" } } } Then, on your server, when you initialize the Firebase app, use the databaseAuthVariableOverride option to override the auth object used by your database rules. In this custom auth object, set the uid field to the identifier you used to represent your service in your Security Rules.
Java
// Fetch the service account key JSON file contentsFileInputStreamserviceAccount=newFileInputStream("path/to/serviceAccountCredentials.json");// Initialize the app with a custom auth variable, limiting the server's accessMap<String,Object>auth=newHashMap<String,Object>();auth.put("uid","my-service-worker");FirebaseOptionsoptions=newFirebaseOptions.Builder().setCredential(FirebaseCredentials.fromCertificate(serviceAccount))// The database URL depends on the location of the database.setDatabaseUrl("https://DATABASE_NAME.firebaseio.com").setDatabaseAuthVariableOverride(auth).build();FirebaseApp.initializeApp(options);// The app only has access as defined in the Security RulesDatabaseReferenceref=FirebaseDatabase.getInstance().getReference("/some_resource");ref.addListenerForSingleValueEvent(newValueEventListener(){@OverridepublicvoidonDataChange(DataSnapshotdataSnapshot){Stringres=dataSnapshot.getValue();System.out.println(res);}});
Node.js
varadmin=require("firebase-admin");// Fetch the service account key JSON file contentsvarserviceAccount=require("path/to/serviceAccountKey.json");// Initialize the app with a custom auth variable, limiting the server's accessadmin.initializeApp({credential:admin.credential.cert(serviceAccount),// The database URL depends on the location of the databasedatabaseURL:"https://DATABASE_NAME.firebaseio.com",databaseAuthVariableOverride:{uid:"my-service-worker"}});// The app only has access as defined in the Security Rulesvardb=admin.database();varref=db.ref("/some_resource");ref.once("value",function(snapshot){console.log(snapshot.val());});
Python
importfirebase_adminfromfirebase_adminimportcredentialsfromfirebase_adminimportdb# Fetch the service account key JSON file contentscred=credentials.Certificate('path/to/serviceAccountKey.json')# Initialize the app with a custom auth variable, limiting the server's accessfirebase_admin.initialize_app(cred,{'databaseURL':'https://databaseName.firebaseio.com','databaseAuthVariableOverride':{'uid':'my-service-worker'}})# The app only has access as defined in the Security Rulesref=db.reference('/some_resource')print(ref.get())
Go
ctx:=context.Background()// Initialize the app with a custom auth variable, limiting the server's accessao:=map[string]interface{}{"uid":"my-service-worker"}conf:=&firebase.Config{DatabaseURL:"https://databaseName.firebaseio.com",AuthOverride:&ao,}// Fetch the service account key JSON file contentsopt:=option.WithCredentialsFile("path/to/serviceAccountKey.json")app,err:=firebase.NewApp(ctx,conf,opt)iferr!=nil{log.Fatalln("Error initializing app:",err)}client,err:=app.Database(ctx)iferr!=nil{log.Fatalln("Error initializing database client:",err)}// The app only has access as defined in the Security Rulesref:=client.NewRef("/some_resource")vardatamap[string]interface{}iferr:=ref.Get(ctx,&data);err!=nil{log.Fatalln("Error reading from database:",err)}fmt.Println(data)
In some cases, you may want to downscope the Admin SDKs to act as an unauthenticated client. You can do this by providing a value of null for the database auth variable override.
Java
// Fetch the service account key JSON file contentsFileInputStreamserviceAccount=newFileInputStream("path/to/serviceAccountCredentials.json");FirebaseOptionsoptions=newFirebaseOptions.Builder().setCredential(FirebaseCredentials.fromCertificate(serviceAccount))// The database URL depends on the location of the database.setDatabaseUrl("https://DATABASE_NAME.firebaseio.com").setDatabaseAuthVariableOverride(null).build();FirebaseApp.initializeApp(options);// The app only has access to public data as defined in the Security RulesDatabaseReferenceref=FirebaseDatabase.getInstance().getReference("/public_resource");ref.addListenerForSingleValueEvent(newValueEventListener(){@OverridepublicvoidonDataChange(DataSnapshotdataSnapshot){Stringres=dataSnapshot.getValue();System.out.println(res);}});
Node.js
varadmin=require("firebase-admin");// Fetch the service account key JSON file contentsvarserviceAccount=require("path/to/serviceAccountKey.json");// Initialize the app with a null auth variable, limiting the server's accessadmin.initializeApp({credential:admin.credential.cert(serviceAccount),// The database URL depends on the location of the databasedatabaseURL:"https://DATABASE_NAME.firebaseio.com",databaseAuthVariableOverride:null});// The app only has access to public data as defined in the Security Rulesvardb=admin.database();varref=db.ref("/public_resource");ref.once("value",function(snapshot){console.log(snapshot.val());});
Python
importfirebase_adminfromfirebase_adminimportcredentialsfromfirebase_adminimportdb# Fetch the service account key JSON file contentscred=credentials.Certificate('path/to/serviceAccountKey.json')# Initialize the app with a None auth variable, limiting the server's accessfirebase_admin.initialize_app(cred,{'databaseURL':'https://databaseName.firebaseio.com','databaseAuthVariableOverride':None})# The app only has access to public data as defined in the Security Rulesref=db.reference('/public_resource')print(ref.get())
Go
ctx:=context.Background()// Initialize the app with a nil auth variable, limiting the server's accessvarnilMapmap[string]interface{}conf:=&firebase.Config{DatabaseURL:"https://databaseName.firebaseio.com",AuthOverride:&nilMap,}// Fetch the service account key JSON file contentsopt:=option.WithCredentialsFile("path/to/serviceAccountKey.json")app,err:=firebase.NewApp(ctx,conf,opt)iferr!=nil{log.Fatalln("Error initializing app:",err)}client,err:=app.Database(ctx)iferr!=nil{log.Fatalln("Error initializing database client:",err)}// The app only has access to public data as defined in the Security Rulesref:=client.NewRef("/some_resource")vardatamap[string]interface{}iferr:=ref.Get(ctx,&data);err!=nil{log.Fatalln("Error reading from database:",err)}fmt.Println(data)
Next Steps
- Learn how to structure data for Realtime Database.
- Scale data across multiple database instances.
- Save data.
- Retrieve data.
- View your database in the Firebase console.
