Use the FCM HTTP v1 API with OAuth 2 access tokens

1. Introduction

Compared to the FCM legacy API, the FCM HTTP v1 API provides a more secure authorization model using short-lived access tokens. The steps for generating the access token for the FCM v1 API are significantly different from the steps for the legacy API.

This codelab walks you through the process of client and server side setup to enable sending push notifications to an Android app using the FCM HTTP v1 API. It highlights the key step of credential generation for the v1 API.

More information can be found at:


  • Basic understanding of Java and Android development

What you'll learn

  • Detailed steps of client and server side setup to enable sending push notifications to your Android app using the FCM HTTP v1 API
  • Credential generation for the HTTP v1 API using service accounts
  • Sending test messages through the HTTP v1 API

What you'll need

Latest stable version of Android Studio

One of the following devices:

A Java development environment or code editor of your choice

2. Firebase project and Android app setup

At the end of the code lab, you'll be able to send messages to your app using Firebase Cloud Messaging. Before doing that, you'll need to create a Firebase project. This codelab also provides an Android app containing sample code to integrate with FCM.

Firebase project setup

Android app setup

The sample Android app provided in this codelab is already integrated with FCM. After starting, it will register with the FCM server and subscribe to a topic. In the later steps of this codelab you'll send a topic message to the topic and your app will receive it.

3. Set up the app server

Now that your app is set up, you'll need to download a server-side code sample for sending messages to your app using the FCM v1 API. This code loads the API credentials (described in the next section) to generate an access token. It then sends a message to your app using FCM topic messaging.

  • Import the starter server code by downloading the Github project. The "messaging" project is a Gradle-based Java project with a dependency on the firebase-admin SDK, which provides functionality to send messages.

More details on how an app server should work with FCM can be found in the document Your server environment and FCM.

4. Get v1 credentials

The FCM HTTP v1 API uses short-lived access tokens according to the OAuth2 security model. Compared to the static API key used in FCM legacy API, the short-lived access token is less prone to the risk of credential leak. This section details the steps to create a credential for generating the access token used in calling the API.

  1. Set up a Firebase service account to let the Firebase Admin SDK authorize calls to FCM APIs. Open Project Settings in the Firebase console and select the Service accounts tab. Click Generate new private key to download the configuration snippet. A cropped screenshot highlighting Admin SDK configuration snippet of Service accounts component of Project settings page
  2. In the downloaded Github project, rename the downloaded file to service-account.json and copy it to messaging/ path of the project.
  3. The getAccessToken() method (shown below) in the class generates an OAuth2 token that's valid for 1 hour.
private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials.fromStream(new FileInputStream("service-account.json")).createScoped(Arrays.asList(SCOPES));
  return googleCredentials.getAccessToken().getTokenValue();
  1. Change the main method to the add the following line:
public static void main(String[] args) throws IOException {
  1. Go to the messaging/ project directory in your terminal, and type:
./gradlew run -Pmessage=common-message

to print out the OAuth2 token.

More information can be found in Authorize send requests.

5. Send a message with the REST API

Now you are ready to send a message through the HTTP v1 API. Follow the steps below:

  • To add the access token to an HTTP request header:
  • Add the token as the value of the Authorization header in the format Authorization: Bearer <access_token>
  • Make an HTTP request to the FCM v1 API using curl:
curl -s -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $OAuth2_token" -H "X-GFE-SSL: yes" -d  "{\"message\": {\"topic\": \"$topic_name\", \"notification\": {\"title\": \"breaking news\", \"body\": \"This is breaking news\"}}}"[PROJECT_NAME]/messages:send

The $topic_name above can be found in the Android app code mentioned in the Firebase project and Android app setup. By default it is "weather".

  • After a message is successfully delivered, you should see a notification pop up on your screen, similar to the image below:


6. Conclusion

Congratulations! You have successfully completed the codelab to:

  • Set up a Firebase project
  • Integrate Firebase with an Android app
  • Create credentials for the FCM HTTP v1 API
  • Send a message to your app through the FCM HTTP v1 API

To explore the advanced features FCM offers, the following references are useful: