Authenticate REST Requests

The Firebase SDKs handle all authentication and communication with the Firebase Realtime Database on your behalf. However, when you're in an environment that doesn't have a client SDK or you want to avoid the overhead of a persistent database connection, you can make use of the Realtime Database REST API to read and write data.

Authenticate users through one of the following methods:

  1. Google OAuth2 access tokens - Typically, the ability to read from and write to the Realtime Database is governed by Realtime Database Rules. But, you can access your data from a server and grant that server full read and write access to your data with a Google OAuth2 access token generated from a service account.

  2. Firebase ID tokens - You might also want to send requests authenticated as an individual user, like limiting access with Realtime Database Rules on the client SDKs. The REST API accepts the same Firebase ID tokens used by the client SDKs.

Google OAuth2 access tokens

Any data that's publicly readable or writable according to your Realtime Database Rules is also readable and writable via the REST API without any authentication. However, if you want your server to bypass your Realtime Database Rules, you need to authenticate your read and write requests. Authentication through Google OAuth2 requires the following steps:

  1. Generate an access token.
  2. Authenticate with that access token.

Generate an access token

The Realtime Database REST API accepts standard Google OAuth2 access tokens. The access tokens can be generated using a service account with proper permissions to your Realtime Database. Clicking the Generate New Private Key button at the bottom of the Service Accounts section of the Firebase console allows you to easily generate a new service account key file if you do not have one already.

Once you have a service account key file, you can use one of the Google API client libraries to generate a Google OAuth2 access token with the following required scopes:

  • https://www.googleapis.com/auth/userinfo.email
  • https://www.googleapis.com/auth/firebase.database

Here are some example implementations that show how to create Google OAuth2 access tokens to authenticate to the Realtime Database REST API in a variety of languages:

Node.js

Using the Google API Client Library for Node.js:

var {google} = require("googleapis");

// Load the service account key JSON file.
var serviceAccount = require("path/to/serviceAccountKey.json");

// Define the required scopes.
var scopes = [
  "https://www.googleapis.com/auth/userinfo.email",
  "https://www.googleapis.com/auth/firebase.database"
];

// Authenticate a JWT client with the service account.
var jwtClient = new google.auth.JWT(
  serviceAccount.client_email,
  null,
  serviceAccount.private_key,
  scopes
);

// Use the JWT client to generate an access token.
jwtClient.authorize(function(error, tokens) {
  if (error) {
    console.log("Error making request to generate access token:", error);
  } else if (tokens.access_token === null) {
    console.log("Provided service account does not have permission to generate access tokens");
  } else {
    var accessToken = tokens.access_token;

    // See the "Using the access token" section below for information
    // on how to use the access token to send authenticated requests to
    // the Realtime Database REST API.
  }
});

Java

Using the Google API Client Library for Java:

// Load the service account key JSON file
FileInputStream serviceAccount = new FileInputStream("path/to/serviceAccountKey.json");

// Authenticate a Google credential with the service account
GoogleCredential googleCred = GoogleCredential.fromStream(serviceAccount);

// Add the required scopes to the Google credential
GoogleCredential scoped = googleCred.createScoped(
    Arrays.asList(
      "https://www.googleapis.com/auth/firebase.database",
      "https://www.googleapis.com/auth/userinfo.email"
    )
);

// Use the Google credential to generate an access token
scoped.refreshToken();
String token = scoped.getAccessToken();

// See the "Using the access token" section below for information
// on how to use the access token to send authenticated requests to the
// Realtime Database REST API.

Python

Using the google-auth library:

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

# Define the required scopes
scopes = [
  "https://www.googleapis.com/auth/userinfo.email",
  "https://www.googleapis.com/auth/firebase.database"
]

# Authenticate a credential with the service account
credentials = service_account.Credentials.from_service_account_file(
    "path/to/serviceAccountKey.json", scopes=scopes)

# Use the credentials object to authenticate a Requests session.
authed_session = AuthorizedSession(credentials)
response = authed_session.get(
    "https://<DATABASE_NAME>.firebaseio.com/users/ada/name.json")

# Or, use the token directly, as described in the "Authenticate with an
# access token" section below. (not recommended)
request = google.auth.transport.requests.Request()
credentials.refresh(request)
access_token = credentials.token

Authenticate with an access token

To send authenticated requests to the Realtime Database REST API, pass the Google OAuth2 access token generated above as the Authorization: Bearer <ACCESS_TOKEN> header or the access_token=<ACCESS_TOKEN> query string parameter. Here is an example curl request to read Ada's name:

curl "https://<DATABASE_NAME>.firebaseio.com/users/ada/name.json?access_token=<ACCESS_TOKEN>"

Make sure to replace <DATABASE_NAME> with the name of your Realtime Database and <ACCESS_TOKEN> with a Google OAuth2 access token.

A successful request will be indicated by a 200 OK HTTP status code. The response contains the data being retrieved:

{"first":"Ada","last":"Lovelace"}

Firebase ID tokens

When a user or device signs in using Firebase Authentication, Firebase creates a corresponding ID token that uniquely identifies them and grants them access to several resources, such as Realtime Database and Cloud Storage. You can re-use that ID token to authenticate the Realtime Database REST API and make requests on behalf of that user.

Generate an ID token

To retrieve the Firebase ID token from the client, follow the steps in Retrieve ID tokens on clients.

Note that ID tokens expire after a short period of time, and should be used as quickly as possible after retrieving them.

Authenticate with an ID token

To send authenticated requests to the Realtime Database REST API, pass the ID token generated above as the auth=<ID_TOKEN> query string parameter. Here is an example curl request to read Ada's name:

curl "https://<DATABASE_NAME>.firebaseio.com/users/ada/name.json?auth=<ID_TOKEN>"

Make sure to replace <DATABASE_NAME> with the name of your Realtime Database and <ID_TOKEN> with a Firebase ID token.

A successful request will be indicated by a 200 OK HTTP status code. The response contains the data being retrieved:

{"first":"Ada","last":"Lovelace"}

Legacy tokens

If you're still using legacy Firebase authentication tokens, we recommend updating your REST authentication to one of the authentication methods described above.

The Realtime Database REST API still supports authentication via legacy authentication tokens, including secrets. Your Realtime Database secrets can be found in the Service Accounts section of the Firebase console.

Secrets are long-lived credentials. We recommend generating a new secret and revoking the existing one when removing users with secret access (such as owners) from a project.