FCM HTTP v1 Migration Guide — Migrate from Legacy API to OAuth 2.0

Google deprecated the FCM legacy HTTP API in June 2024. If you're still using a server key to send notifications, it's time to migrate to the HTTP v1 API.

Why Migrate?

The legacy API (https://fcm.googleapis.com/fcm/send) has several limitations:

• Deprecated — Google will eventually shut it down
• No platform overrides — Can't customize per platform
• Simple API key — Less secure than OAuth 2.0
• Limited error reporting — Generic error messages

The HTTP v1 API offers:

• OAuth 2.0 security with service account keys
• Platform-specific configs for Android, iOS, and Web
• Better error messages with detailed codes
• Analytics labels for tracking delivery

Step 1: Create a Service Account

1. Go to Firebase Console → Project Settings → Service Accounts
2. Click "Generate new private key"
3. Save the JSON file securely

Step 2: Update Your Endpoint

Change from:

POST https://fcm.googleapis.com/fcm/send
Authorization: key=YOUR_SERVER_KEY

To:

POST https://fcm.googleapis.com/v1/projects/YOUR_PROJECT_ID/messages:send
Authorization: Bearer YOUR_OAUTH_TOKEN

Step 3: Update Your Payload

Legacy format:

jsonCopy
{
  "to": "DEVICE_TOKEN",
  "notification": {
    "title": "Hello",
    "body": "World"
  }
}

V1 format:

jsonCopy
{
  "message": {
    "token": "DEVICE_TOKEN",
    "notification": {
      "title": "Hello",
      "body": "World"
    }
  }
}

Key differences:

• Wrap everything in a message object
• Use token instead of to
• Use topic instead of /topics/topicname

Step 4: Generate OAuth Tokens

Use your service account JSON to generate short-lived OAuth 2.0 tokens. Most server SDKs handle this automatically:

javascriptCopy
// Node.js with google-auth-library
const { GoogleAuth } = require('google-auth-library');
const auth = new GoogleAuth({
  keyFile: 'service-account.json',
  scopes: ['https://www.googleapis.com/auth/firebase.messaging']
});
const client = await auth.getClient();
const token = await client.getAccessToken();

Step 5: Test with Our Tool

Use the FCM Tester to verify your setup works before deploying. Just paste your service account JSON and send a test message.

Common Migration Issues