Use the Admin SDK with Data Connect

The Firebase Admin SDK is a set of server libraries that lets you interact with Firebase from privileged environments to perform actions like performing queries and mutations on a Firebase Data Connect service for bulk data management and other operations with elevated privileges and impersonated credentials.

The Admin SDK provides you with an API to call operations in both read/write and read-only modes. With the read-only operations, you have the peace of mind of implementing administrative functions that cannot modify data in your databases.

Admin SDK Setup

To get started using the with Firebase Data Connect on your server, you'll first need to install and set up the Admin SDK for Node.js.

Initialize the Admin SDK in your scripts

To initialize the SDK, import the Data Connect extensions and declare your project service ID and location.


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

// If you'd like to use OAuth2 flows and other credentials to log in,
// visit https://firebase.google.com/docs/admin/setup#initialize-sdk
// for alternative ways to initialize the SDK.

const app = initializeApp();

const dataConnect = getDataConnect({
    serviceId: 'serviceId',
    location: 'us-west2'
});

Design queries and mutations to use with the Admin SDK

The Admin SDK is useful for testing Data Connect operations, given the following considerations.

Understand the SDK and @auth(level: NO_ACCESS) operation directive

Since the Admin SDK operates with privileges, it can execute any of your queries and mutations regardless of access levels set using @auth directives, including the NO_ACCESS level.

If alongside your client operations, you organize your administrative queries and mutations in .gql source files for import into administrative scripts, Firebase recommends that you mark the administrative operations without any authorization access level, or perhaps be more explicit and set them as NO_ACCESS. Either way, this prevents such operations from being executed from clients or in other non-privileged contexts.

Use the SDK with the Data Connect emulator

In prototype and test environments, it can be useful to perform data seeding and other operations on local data. The Admin SDK lets you simplify your workflows since it ignores authentication and authorization for local flows.

The Firebase Admin SDKs automatically connects to the Data Connect emulator when the DATA_CONNECT_EMULATOR_HOST environment variable is set:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

For more information, see:

Implement common use cases

The Admin SDK is provided for privileged operations on your critical data.

The API for Data Connect consists of a read-write executeGraphql interface and a read-only executeGraphqlRead interface.

Manage user data

A typical use case for the Admin SDK is managing user data.

Use administrative credentials

The most straightforward approach is to access user data using administrative credentials.

// User can be publicly accessible, or restricted to admins
const query = "query getProfile(id: AuthID) { user(id: $id) { id name } }";

interface UserData {
  user: {
    id: string;
    name: string;
  };
}

export interface UserVariables {
  id: string;
}

const options:GraphqlOptions<UserVariables> = { variables: { id: "QVBJcy5ndXJ1" } };

// executeGraphql
const gqlResponse = await dataConnect.executeGraphql<UserData, UserVariables>(query, options);

// executeGraphqlRead (similar to previous sample but only for read operations)
const gqlResponse = await dataConnect.executeGraphqlRead<UserData, UserVariables>(query, options);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

Impersonate user credentials

There are also use cases where you want your scripts to modify user data based on limited credentials, on behalf of a specific user. This approach honors the principle of least privilege.

To use this interface, gather information from a customized JWT auth token that follows the Authentication token format. Also see the custom tokens guide.

// Get the current user's data
const queryGetUserImpersonation = `
    query getUser @auth(level: USER) {
        user(key: {uid_expr: "auth.uid"}) {
            id,
            name
        }
    }`;

// Impersonate a user with the specified auth claims
const optionsAuthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        authClaims: {
            sub: 'QVBJcy5ndXJ1'
        }
    }
};

// executeGraphql with impersonated authenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetUserImpersonation, optionsAuthenticated);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

Manage public data

You can work with publicly-acessible data using the SDK, impersonating an unauthenticated user.

// Query to get posts, with authentication level PUBLIC
const queryGetPostsImpersonation = `
    query getPosts @auth(level: PUBLIC) {
        posts {
          description
        }
    }`;

// Attempt to access data as an unauthenticated user
const optionsUnauthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        unauthenticated: true
    }
};

// executeGraphql with impersonated unauthenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetPostsImpersonation, optionsUnauthenticated);

What's next?