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:

Video: Introducing Firebase Cloud Messaging
The FCM Architectural Overview

Prerequisites

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 physical Android device connected to your computer
An Android emulator (see Run apps on the Android Emulator)

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

Follow "Step 1: Create a Firebase Project" to create your own Firebase project for this codelab.

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.

Download the Firebase Android quickstart sample.
Import the project under https://github.com/firebase/quickstart-android/tree/master/messaging to Android Studio.
Register the app in Firebase Console. The app name is com.google.firebase.quickstart.fcm. Register this app in your Firebase project by following the steps in "Step 2: Register your app with Firebase" section.
Follow part 1 of "Step 3: Add a Firebase configuration file" to download google-services.json and add it to your project. Build and run the project.

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.

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.
In the downloaded Github project, rename the downloaded file to service-account.json and copy it to messaging/ path of the project.
The getAccessToken() method (shown below) in the Messaging.java 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));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}

Change the main method to the add the following line:

public static void main(String[] args) throws IOException {
  System.out.println(getAccessToken());
  ...
}

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\"}}}" https://fcm.googleapis.com/v1/projects/[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: