Android Firebase credentials

To send push notifications to Android devices with Google Play services, you need two things from the same Firebase project:

An FCM Service Account private key, uploaded to OneSignal. This authorizes OneSignal’s servers to send to your Firebase project. Required.
A google-services.json file, added to your app. This is Firebase client configuration that ships inside your app. Recommended for all new integrations, and required for Firebase Installation ID registration.

These instructions do not apply to:

Web Push. Android devices can subscribe to your website or PWA without an FCM Service Account. See Web push setup.
Huawei devices without Google Play services. See Huawei Authorization.
Amazon devices (Fire OS). See Amazon API key generation.

Requirements

An Android app that runs on devices with Google Play services, including Google Play, sideloaded, and internal builds
A OneSignal account
A Firebase account (free)

Create a Firebase Service Account private key

Create or open your Firebase Project

Go to your Firebase console and either create or select a project.

Firebase console showing the list of available projects — Page of Projects within Firebase

Enable Firebase Cloud Messaging API V1

In your Firebase project’s Settings, select the Cloud Messaging tab.

Firebase Project settings showing the Cloud Messaging tab with the Firebase Cloud Messaging API (V1) status as Enabled — Cloud Messaging tab in Firebase Project settings

Check the Firebase Cloud Messaging API (V1) status:

Enabled (green checkmark) means Google accepts Cloud Messaging send requests for this project.
Disabled means Google rejects those requests, so Android push notifications do not deliver. Enable this by clicking the 3-dot menu > Manage API in Google Cloud Console, then click Enable and wait until the status shows API Enabled with a green checkmark.

Google Cloud Console Firebase Cloud Messaging API page showing the API Enabled status with a green checkmark — Firebase Cloud Messaging API enabled in the Google Cloud Console

Enabling the API does not grant the Service Account any roles. If someone else owns the Firebase project or Google account, check your Service Account permissions first.

Generate a new private key

Back in Project settings, select the Service accounts tab and click Generate new private key.

Service accounts tab in Firebase Project settings showing the Generate new private key button — Service Accounts section within Firebase

Confirm by clicking Generate key in the popup.

Firebase confirmation dialog for generating a new private key for the service account — Generate the private key for the service account.

The downloaded private key contains sensitive credentials. Do not share it or check it into version control.

Save the .json file in a secure location. You upload it to OneSignal in the next section.

Upload the Service Account private key to OneSignal

Upload the private key so OneSignal’s servers can send push notifications through your Firebase project.

Open Android settings

Go to Settings > Push & In-App and follow the steps to reach Google Android (FCM) configuration.

Upload your Service Account private key

Click Select file and choose the .json private key you saved in the previous section.

OneSignal Google Android (FCM) configuration screen with the Service Account JSON file upload field and Select file button — FCM configuration screen

Save and continue

Click Save & Continue. OneSignal validates the private key and moves you to SDK selection.

If the dashboard shows Invalid request, the Service Account is likely missing a required role. See How do I check my Service Account permissions?

Add your Firebase configuration file

Your app needs a google-services.json file from the same Firebase project as your Service Account above. Do not upload this file to OneSignal. It belongs in your app’s source code and tells your app which Firebase project to register with. On OneSignal Android SDK 5.11.0 and later, the SDK registers through your Firebase project when your google-services.json matches the Sender ID in OneSignal. Otherwise the SDK uses OneSignal’s shared Firebase project. See What happens if I skip google-services.json?

Upgrading an existing app? Delivery keeps using the same Firebase project and Service Account, but:

Each device gets a new push token value the next time it opens the updated app. Its Subscription is preserved, and the old token works until then.
Your Firebase console FCM metrics start including OneSignal registrations.
Your Firebase token calls now affect OneSignal. Calling FirebaseMessaging.getInstance().deleteToken() (on logout, for example) also deletes the OneSignal registration until the SDK re-registers. With Firebase Installation ID registration, the equivalent call is unregister().

Plan to add the file eventually. Without it, your app stays on legacy FCM registration tokens, which Firebase has deprecated.

Download google-services.json

In your Firebase console, open the project you used for the Service Account private key. Go to Project settings > General, then scroll to Your apps. If your Android app is not listed, click Add app.Confirm the Android package name matches your app’s applicationId, then download google-services.json.

Add it to your app

Your app never reads the file at runtime. A build step converts it into Android resources, and without that step the file does nothing. Find your platform below and follow its setup guide.

Platform	Takes effect from	Where the file goes	How it is processed
Android (native)	`5.11.0`	`app/google-services.json`	Apply `com.google.gms.google-services` in the app module
Flutter	`5.7.2`	`android/app/google-services.json`	Declare the plugin in `android/settings.gradle` and apply it in `android/app/build.gradle`. The OneSignal Flutter plugin cannot apply it for you
React Native	`5.5.16`	`android/app/google-services.json`	Declare and apply the plugin in the Android app module, or reuse an existing React Native Firebase setup
Expo	`react-native-onesignal` `5.5.16`	Any path, referenced by `android.googleServicesFile` in your app config	`expo prebuild` copies the file and applies the plugin. `android.package` must match a client entry in the file. Requires a dev build, not Expo Go
Capacitor	`1.2.2`	`android/app/google-services.json`	Automatic. Capacitor’s Android template already carries the plugin and applies it when the file is present
Cordova	`5.6.2`	Project root, copied to `platforms/android/app/` by a `<resource-file>` entry in `config.xml`	Set `<preference name="GradlePluginGoogleServicesEnabled" value="true" />` in `config.xml`
Unity	`5.4.2`	No JSON at runtime. Ship `res/values/google-services.xml` inside an `.androidlib` under `Assets/Plugins/Android`	No plugin step. `FirebaseInitProvider` reads the resources directly. The Firebase Unity SDK generates this file from `google-services.json`
.NET / MAUI	`6.4.2`	`Platforms/Android/google-services.json`	Reference it with `<GoogleServicesJson Include="Platforms\Android\google-services.json" />`

On SDK versions earlier than the ones listed above, the file is safe to add but does nothing for OneSignal. Push keeps registering through OneSignal’s shared Firebase project until you upgrade.

Apply the Google Services Gradle plugin

This step is for Android native, React Native, and Flutter only. Other platforms handle the plugin as described in the table above.The plugin resolves from Google’s Maven repository. Confirm google() is listed under pluginManagement in settings.gradle or settings.gradle.kts, or the build fails with Plugin [id: 'com.google.gms.google-services'] was not found:

settings.gradle.kts

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Add the plugin to your project-level Gradle file:

plugins {
    id("com.google.gms.google-services") version "[4.4.2, 4.99.99]" apply false
}

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:[4.4.2, 4.99.99]'
    }
}

Then apply it in your app-level Gradle file:

plugins {
    id("com.google.gms.google-services")
}

apply plugin: 'com.google.gms.google-services'

If your project uses a Gradle version catalog, declare the version there instead of in the project-level file. The app-level step above is unchanged.

[versions]
google-services = "[4.4.2, 4.99.99]"

[plugins]
google-services = { id = "com.google.gms.google-services", version.ref = "google-services" }

plugins {
    alias(libs.plugins.google.services) apply false
}

Sync Gradle.The range keeps you on the latest 4.x plugin. To pin a specific release, see Google’s documentation.

Verify the file took effect

Build your app, then confirm the plugin generated Firebase’s string resources:

./gradlew :app:processDebugGoogleServices
grep -r "google_app_id\|project_id" app/build/generated/res/

If google_app_id and project_id appear, the file took effect. A successful build alone does not prove it.

Neither value appears: the plugin is not applied. Adding the file without the plugin produces no error.
File google-services.json is missing: the plugin is applied, but the file is not where your toolchain expects it. Check the table above.
No matching client found for package name: the package registered in Firebase does not match your applicationId. Fix it in the Firebase console and download the file again.
The file comes from a different Firebase project than your Service Account: see Match your Firebase projects.

Set up Firebase without google-services.json

Initialize the default FirebaseApp in code if you can’t use the Google Services Gradle plugin, or if you load Firebase only after user consent. Use values from the same Firebase project as the Service Account private key you uploaded to OneSignal:

val options = FirebaseOptions.Builder()
    .setProjectId("YOUR_FIREBASE_PROJECT_ID")
    .setApplicationId("1:123456789012:android:abcdef123456")
    .setApiKey("YOUR_FIREBASE_API_KEY")
    .setGcmSenderId("123456789012")
    .build()

FirebaseApp.initializeApp(context, options)

Initialize Firebase before OneSignal initializes. A storage bucket is not required for push. If initialization has not completed by the time OneSignal registers for push:

On the legacy token path, the SDK registers through OneSignal’s shared Firebase project for that session, and uses your project on a later session.
With Firebase Installation ID registration turned on, registration fails with status -32 and retries on a later session.

Match your Firebase projects

Your app must register with the same Firebase project as the Service Account private key you uploaded to OneSignal. When the projects differ:

On the legacy token path, the OneSignal SDK registers through OneSignal’s shared Firebase project and logs a warning.
With Firebase Installation ID registration turned on, registration fails with status -6, and existing Subscriptions are marked invalid.

Compare either value below. A Firebase project’s Project ID and Project Number are permanently paired, so if one matches, both do.

OneSignal dashboard	Your `google-services.json`
Firebase Project ID Settings > Push & In-App > Google Android (FCM)	`project_info.project_id`
Sender ID (Project Number)	`project_info.project_number`

Your google-services.json looks like this:

google-services.json

{
  "project_info": {
    "project_number": "388536902528",
    "project_id": "my-app-12345"
  },
  "client": [{
    "client_info": {
      "mobilesdk_app_id": "1:388536902528:android:a1b2c3d4e5f6",
      "android_client_info": { "package_name": "com.example.myapp" }
    }
  }]
}

FAQ

What happens if I skip google-services.json?

Push notifications still work today. The OneSignal SDK registers through OneSignal’s shared Firebase project, using FCM registration tokens. Google has deprecated FCM registration tokens in favor of Firebase Installation IDs. The shared project can’t register with Firebase Installation IDs, so adding google-services.json now prepares your app for that change if and when Google starts requiring Firebase Installation IDs. Without the file, you also can’t turn on Firebase Installation ID registration.

How do I check my Service Account permissions?

Service Account roles are granted on the IAM page in the Google Cloud Console, not in the Firebase Console and not on the Service Accounts page. The Service Account whose private key you upload to OneSignal needs these two roles:

Role to add	What it lets OneSignal do	Permission it grants
Firebase Cloud Messaging API Admin	Send push notifications through your Firebase project	`cloudmessaging.messages.create`
Firebase Viewer	Read your Firebase project details	`firebase.projects.get`

Broader roles like Firebase Admin (roles/firebase.admin), Editor, or Owner include both permissions and also satisfy the requirement. For OneSignal-only Service Accounts, prefer the narrow pair above to limit the impact if the private key is ever exposed. If the OneSignal dashboard shows Invalid request after you upload your Service Account private key, missing roles are the most common cause.

Open the IAM page

In the Google Cloud Console, set the project picker to the Firebase project, not the organization. In the left nav, open IAM & Admin and click IAM.The page is a table with Principal, Name, and Role columns. Do not use Service Accounts > Permissions. That page lists who can use the account, not which roles the account has on the project.

Find your Service Account

Find the row whose principal email matches the client_email field in the private key you uploaded. It looks like firebase-adminsdk-xxxxx@YOUR_PROJECT_ID.iam.gserviceaccount.com. Paste that email into the filter box if the table is long.

Add any missing roles

On that row, click the pencil (Edit principal). In the Edit permissions panel, click Add another role and add Firebase Cloud Messaging API Admin and Firebase Viewer if they are not already assigned. Skip this if the account already has Firebase Admin, Editor, or Owner.

Save

Click Save. The new roles can take about a minute to apply.

Why am I seeing “This configuration is for a different Firebase Project”?

This error occurs when the uploaded private key belongs to a different Firebase project (a different Sender ID). Solution: Use the original Firebase project’s private key. If unavailable, contact support@onesignal.com with your App ID. Switching projects resets push tokens. Your users must reopen the app to get push again. The reverse also happens: the uploaded key is correct, but the app ships a google-services.json from a different Firebase project. See Match your Firebase projects.

Can I change my Sender ID?

Yes, but changing it invalidates existing device tokens, because tokens are tied to the original Sender ID. Users stop receiving push notifications until they reopen the app and get a new token. For help, contact support@onesignal.com with your App ID.

Why don’t I see a Sender ID in OneSignal?

If your Firebase server key looks like AIz..., you’re likely using an outdated Google Cloud Messaging (GCM) setup. Add Firebase to your existing Google Cloud project to keep your Sender ID, then upload a Service Account private key. Creating a new Firebase project gives you a new Sender ID, which invalidates existing push tokens. See Can I change my Sender ID?

Do I need to update my code when switching to FCM V1?

No app or SDK changes are required. This is a dashboard-only update.

Are the legacy FCM APIs still supported?

No. Google’s legacy FCM APIs are fully deprecated and no longer deliver notifications. If your app still uses them, upload a Service Account private key as described above to move to FCM V1.

How can I check which apps are still using the Legacy API?

Call the View an app API for each app and check the fcm_v1_service_account_json field in the response:

Present and non-empty: the app is on FCM V1.
Missing or empty: the app is not configured for FCM V1. If the app sends Android push, it is still on the Legacy API and must be migrated.

To list your apps and their App IDs first, use the View apps API.

What is Firebase Cloud Messaging, and why does OneSignal need a Service Account private key?

Firebase Cloud Messaging (FCM) is Google’s service for delivering push notifications to Android devices. A Service Account is a Google identity that OneSignal uses to authenticate to your Firebase project, and its private key is a JSON file that proves the identity. Uploading the private key authorizes OneSignal to send pushes through Firebase on your behalf. For more details, see Google’s Service Account documentation.

Mobile SDK setup

Install and initialize the OneSignal SDK in your Android app.

Firebase Installation ID registration

Check whether FID registration is enabled in your app, and enable or disable it.

Huawei push setup

Authorize OneSignal to send push to Huawei devices without Google Play services.

Amazon push setup

Generate an Amazon API key to send push to Fire OS devices.

Web push setup

Configure push notifications for websites.

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

Requirements

Create a Firebase Service Account private key

Upload the Service Account private key to OneSignal

Add your Firebase configuration file

Verify the file took effect

Set up Firebase without google-services.json

Match your Firebase projects

FAQ

What happens if I skip google-services.json?

How do I check my Service Account permissions?

Why am I seeing “This configuration is for a different Firebase Project”?

Can I change my Sender ID?

Why don’t I see a Sender ID in OneSignal?

Do I need to update my code when switching to FCM V1?

Are the legacy FCM APIs still supported?

How can I check which apps are still using the Legacy API?

What is Firebase Cloud Messaging, and why does OneSignal need a Service Account private key?

Mobile SDK setup

Firebase Installation ID registration

Huawei push setup

Amazon push setup

Web push setup

​Requirements

​Create a Firebase Service Account private key

​Upload the Service Account private key to OneSignal

​Add your Firebase configuration file

​Verify the file took effect

​Set up Firebase without google-services.json

​Match your Firebase projects

​FAQ

​What happens if I skip google-services.json?

​How do I check my Service Account permissions?

​Why am I seeing “This configuration is for a different Firebase Project”?

​Can I change my Sender ID?

​Why don’t I see a Sender ID in OneSignal?

​Do I need to update my code when switching to FCM V1?

​Are the legacy FCM APIs still supported?

​How can I check which apps are still using the Legacy API?

​What is Firebase Cloud Messaging, and why does OneSignal need a Service Account private key?

​Related pages

Mobile SDK setup

Firebase Installation ID registration

Huawei push setup

Amazon push setup

Web push setup

Requirements

Create a Firebase Service Account private key

Upload the Service Account private key to OneSignal

Add your Firebase configuration file

Verify the file took effect

Set up Firebase without google-services.json

Match your Firebase projects

FAQ

What happens if I skip google-services.json?

How do I check my Service Account permissions?

Why am I seeing “This configuration is for a different Firebase Project”?

Can I change my Sender ID?

Why don’t I see a Sender ID in OneSignal?

Do I need to update my code when switching to FCM V1?

Are the legacy FCM APIs still supported?

How can I check which apps are still using the Legacy API?

What is Firebase Cloud Messaging, and why does OneSignal need a Service Account private key?

Related pages