iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
🔑

Week 05: Solving FCM 'third-party-auth-error' caused by the wrong APNs key - Pitfalls of Apple .p8 key management

に公開
Firebase
iOS
FCM
Apple
apns
tech

Introduction

When attempting to send push notifications to iOS using Firebase Cloud Messaging (FCM), all requests failed.

The error was messaging/third-party-auth-error. In the Cloud Functions logs, success=0, failure=1 was repeated.

The cause was the APNs key. To be precise, the file I had registered, believing it to be an APNs key, was not an APNs key at all.

In this article, I will share the investigation steps taken when encountering third-party-auth-error in FCM iOS notifications, and the common traps when managing Apple .p8 keys.

1. The Issue

I was sending notifications via the FCM v1 API from Cloud Functions v2. All requests failed with:

messaging/third-party-auth-error

The APNs key was registered in the Firebase Console's Cloud Messaging settings, including both the Key ID and Team ID. At first glance, the settings appeared correct.

2. Investigation

What I suspected first (Incorrect)

  • Insufficient IAM Roles: Assigned the Firebase Cloud Messaging API Admin role to the Cloud Functions v2 Compute Engine default service account → No change.
  • firebase-admin SDK version: Suspected changes in the v13 API → Unrelated.

Both were wrong. third-party-auth-error is an authentication error between Firebase and Apple; IAM and SDK versions are irrelevant. As the error name implies, the problem lies in "authentication with a third party (Apple)."

Effective Investigation: Directly invoking the FCM v1 API

Error details are not visible via Cloud Functions. I called the FCM v1 API directly to check the response details.

curl -X POST \
  "https://fcm.googleapis.com/v1/projects/{PROJECT_ID}/messages:send" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "token": "{DEVICE_TOKEN}",
      "notification": { "title": "test", "body": "test" }
    }
  }'

The response contained a detailed error from APNs:

InvalidProviderToken (403)

InvalidProviderToken is an error occurring when APNs "cannot verify the provided authentication token." In other words, there is an issue with the APNs key registered in Firebase.

3. Root Cause

I checked the .p8 key that was registered in Firebase Cloud Messaging.

The Key ID was XXXXXXXXXX.

This key was actually an App Store Connect API key obtained for RevenueCat. It was not an APNs key.

Why I didn't notice

The file format for a .p8 key is the same regardless of its purpose. The filename is also standardized as AuthKey_XXXXX.p8. Even looking at the content, both are ECDSA P-256 private keys, making them indistinguishable by sight.

"A .p8 is a .p8, right? They should all be usable in the same way."—this assumption was the cause.

4. The Pitfalls of Apple .p8 Keys

Apple's .p8 keys are issued from several different locations, each serving a different purpose. Although the file format is the same, they are not interchangeable.

Issuer and Purpose

Issuer Purpose Usage
Apple Developer → Certificates, Identifiers & Profiles → Keys APNs (Push Notifications) Firebase Cloud Messaging
Apple Developer → Certificates, Identifiers & Profiles → Keys Sign In with Apple Firebase Auth
App Store Connect → Users and Access → Integrations → Keys App Store Connect API RevenueCat, Fastlane, etc.
App Store Connect → Users and Access → Integrations → In-App Purchase In-App Purchase Server-side billing verification

How to Distinguish Them

The XXXXX in the filename AuthKey_XXXXX.p8 is the Key ID, but it does not indicate the purpose on its own.

Verification method:

  • Keys displayed in Apple Developer → Keys are for APNs / Sign In with Apple.
  • Keys displayed in App Store Connect → Integrations → Keys are for API usage.
  • Keys displayed in App Store Connect → Integrations → In-App Purchase are for billing verification.

You must register the key issued via Apple Developer → Keys with APNs enabled into Firebase Cloud Messaging. Registering an App Store Connect API key here will also result in an InvalidProviderToken error.

5. Proper Management Method

Managing by Purpose in Folders

_credentials/
├── apns/
│   └── AuthKey_YYYYYYYYYY.p8    # For APNs
├── auth/
│   └── AuthKey_ZZZZZZZZZZ.p8    # For Sign In with Apple
├── revenuecat/
│   └── AuthKey_XXXXXXXXXX.p8    # For App Store Connect API
└── README.md                     # Usage, issuer, and registration site for each key

Documentation

Record the following for each key:

Item Content
Key ID YYYYYYYYYY
Issuer Apple Developer → Keys
Purpose APNs (Push Notifications)
Registration Site Firebase Console → Cloud Messaging (dev/prod)
Date Created 2026-03-02
Notes Sandbox & Production, Team Scoped

Since you can only download a .p8 file once, losing it requires re-issuance. It is crucial to clearly track where they are stored and what their purpose is.

6. Fix Steps

I have documented the fix steps I followed:

  1. Apple Developer Console → Keys: Create a new key.

    • Name: Push Notifications (Do not include the app name; use a shared key for all apps).
    • Service: Enable Apple Push Notifications service (APNs).
    • Download the .p8 file (one-time only).

  2. Firebase Console → Cloud Messaging: Change settings.

    • Remove the incorrect key.
    • Register the new APNs key (Key ID + Team ID + .p8 file).
    • Perform this for both dev and prod environments.

  3. Verification

    • Perform an action from a different account (e.g., "Like").
    • Confirm that the notification banner appears on the device.

The fix itself took only an hour to complete.

7. Lessons Learned

When encountering third-party-auth-error

  1. Do not use Cloud Functions; call the FCM v1 API directly to check detailed APNs errors.
  2. If you see InvalidProviderToken, suspect the purpose of the registered key.
  3. Verify which key in the Apple Developer → Keys portal corresponds to the Key ID registered in the Firebase Console → Cloud Messaging.

When handling .p8 keys

  • Even if file formats are the same, if the issuer is different, they are not compatible.
  • You cannot determine the purpose from the Key ID alone. Manage them using folder structures and documentation.
  • Do not proceed with an assumption that "this key must be correct"; cross-reference the issuer and purpose.

Troubleshooting Configuration Issues in General

Problems involving third-party-auth-error cannot be solved by looking only at code or logs. It is significantly faster to check the management consoles of Firebase and Apple Developer directly.

Whether the registered Key ID belongs to the correct issuer can only be determined by cross-referencing with the management console. Trying to confirm indirectly via tools or APIs is a detour.

I have summarized the background of this incident and the "strengths and weaknesses of AI" I discovered during development in another article.

https://zenn.dev/deke_pearson700/articles/6a12b3e4a46fe0

Here are my weekly development logs on note:
https://note.com/duke_pearson700/n/n8e49f7a4eae8

Discussion