Firebase Appcheck Manager

Firebase App Check Manager

⚠️ #1 ROOT CAUSE of "App attestation failed": Missing Team ID or API not enabled

Two things MUST be in place for iOS App Check to work:

1. firebaseappcheck.googleapis.com API must be ENABLED — even if you've configured providers in Console, if this API isn't enabled, all token exchanges fail silently.
2. iOS App must have teamId set — Without Team ID, App Attest cannot verify with Apple's servers.

Team ID can be set via REST API (no Console UI needed):

curl -X PATCH -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"YOUR_TEAM_ID"}' \
  "https://firebase.googleapis.com/v1beta1/projects/${PROJECT_ID}/iosApps/${IOS_APP_ID}?updateMask=teamId"

If Team ID is already set and API is enabled, verify app registration through Firebase Console → App Check → 應用程式 tab. Required IAM role: roles/editor or roles/owner (not just roles/firebase.viewer or roles/firebaseappcheck.admin).

Manage Firebase App Check configuration entirely via CLI (gcloud + REST API). No Firebase Console UI needed for most steps, except app registration (see Step 0).

Concepts: How App Check Works

App Check is a server-side gatekeeper that protects your Firebase backend services from abuse. It works via a 3-step process:

┌─────────────┐     ①  Attestation      ┌────────────────────┐
│  Your App   │ ──────────────────────→  │  Attestation       │
│ (Flutter)   │                          │  Provider          │
│             │ ←────────────────────    │ (Play Integrity /  │
│             │     ② Attestation Token  │  App Attest)       │
│             │                          └────────────────────┘
│             │     ③ Exchange for
│             │        App Check Token   ┌────────────────────┐
│             │ ──────────────────────→  │  Firebase           │
│             │                          │  App Check Server   │
│             │ ←────────────────────    │                     │
│             │     ④ App Check Token    └────────────────────┘
│             │
│             │     ⑤ API call with      ┌────────────────────┐
│             │        App Check Token   │  Firebase Service   │
│             │ ──────────────────────→  │  (AI, Firestore,   │
│             │                          │   Storage, etc.)    │
│             │     ⑥ Response           └────────────────────┘
└─────────────┘     (or 403 if invalid)

Critical understanding:

• The activate() call in Flutter just tells the SDK to start sending tokens
• Without enforcement on the server side, those tokens are ignored — ANY request is accepted
• Enforcement = server rejects requests without valid App Check tokens
• You must enable enforcement per Firebase service independently

Android: Three Signing Keys

Android apps have three different signing keys. All three produce different SHA-256 fingerprints. All three must be registered in Firebase for App Check to work across dev, testing, and production:

⚠️ The #1 mistake: Registering only the debug or upload key. Production users receive the app signed with the App Signing Key which is different — their App Check attestation will fail silently.

iOS: App Attest vs DeviceCheck

⚠️ CRITICAL: Always use appAttestWithDeviceCheckFallback in production, NOT appAttest alone.

App Attest depends on Apple's attestation server. Even on iOS 14+ real devices, ExchangeAppAttestAttestation has a ~25% failure rate due to:

• Apple attestation server transient failures
• First-time attestation timing issues on fresh installs
• Network conditions during attestation handshake
• Device state edge cases (not jailbreak related)

appAttestWithDeviceCheckFallback tries App Attest first, and automatically falls back to DeviceCheck when App Attest fails. Both are Apple official attestation mechanisms with equivalent security for App Check purposes. This ensures near-100% token acquisition rate.

Firebase Console must have both App Attest AND DeviceCheck providers registered for the iOS app.

iOS entitlement required: You MUST add com.apple.developer.devicecheck.appattest-environment to your iOS entitlements for App Attest to work in production builds.

Prerequisites

• gcloud CLI authenticated with the correct account (gcloud auth list / gcloud config set account EMAIL)
• Owner/Editor role on the Firebase project
• Know your Firebase Project ID and App IDs (firebase apps:list --project=PROJECT_ID)

Common Header Pattern

All REST API calls need these headers:

ACCESS_TOKEN=$(gcloud auth print-access-token)
PROJECT_ID="your-project-id"
ANDROID_APP_ID="1:xxxx:android:xxxx"
IOS_APP_ID="1:xxxx:ios:xxxx"
PROJECT_NUMBER="123456789"  # from firebase projects:list

-H "Authorization: Bearer $ACCESS_TOKEN"
-H "x-goog-user-project: ${PROJECT_ID}"
-H "Content-Type: application/json"

Important: The x-goog-user-project header is required for quota billing. Without it you get SERVICE_DISABLED errors.

Quick Audit Script (One-Shot Health Check)

Run this script to get a full status of App Check for any Firebase project. Copy/paste the entire block:

#!/bin/bash
# Usage: Set the 5 variables below, then run the entire script

ACCESS_TOKEN=$(gcloud auth print-access-token)
PROJECT_ID="your-project-id"
PROJECT_NUMBER="123456789"
ANDROID_APP_ID="1:xxxx:android:xxxx"
IOS_APP_ID="1:xxxx:ios:xxxx"

echo "╔═══════════════════════════════════════════╗"
echo "║   Firebase App Check Audit: $PROJECT_ID   ║"
echo "╚═══════════════════════════════════════════╝"
echo ""

# 1. API Enablement
echo "── 1. API Enablement ──"
AC=$(gcloud services list --enabled --filter="config.name:firebaseappcheck" --project=$PROJECT_ID --format="value(config.name)" 2>/dev/null)
PI=$(gcloud services list --enabled --filter="config.name:playintegrity" --project=$PROJECT_ID --format="value(config.name)" 2>/dev/null)
[ -n "$AC" ] && echo "  ✅ firebaseappcheck.googleapis.com ENABLED" || echo "  ❌ firebaseappcheck.googleapis.com NOT ENABLED"
[ -n "$PI" ] && echo "  ✅ playintegrity.googleapis.com ENABLED" || echo "  ❌ playintegrity.googleapis.com NOT ENABLED"
echo ""

# 2. Services Enforcement
echo "── 2. Services Enforcement ──"
SERVICES=$(curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/services")
if echo "$SERVICES" | python3 -c "import sys,json; d=json.load(sys.stdin); svcs=d.get('services',[]); [print(f'  {s[\"name\"].split(\"/\")[-1]}: {s.get(\"enforcementMode\",\"UNENFORCED\")}') for s in svcs]" 2>/dev/null; then
  :
else
  echo "  ⚠️  No services configured or empty response"
fi
echo ""

# 3. Android Play Integrity Config
echo "── 3. Android Play Integrity Config ──"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/apps/${ANDROID_APP_ID}/playIntegrityConfig" | python3 -c "
import sys,json
d=json.load(sys.stdin)
ttl=d.get('tokenTtl','?')
lvl=d.get('deviceIntegrity',{}).get('minDeviceRecognitionLevel','?')
print(f'  Token TTL: {ttl}')
print(f'  Min Device Recognition: {lvl}')
if lvl == 'NO_INTEGRITY':
    print('  ⚠️  NO_INTEGRITY allows any device (including emulators)')
" 2>/dev/null
echo ""

# 4. iOS App Attest Config
echo "── 4. iOS App Attest Config ──"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/apps/${IOS_APP_ID}/appAttestConfig" | python3 -c "
import sys,json
d=json.load(sys.stdin)
print(f'  Token TTL: {d.get(\"tokenTtl\",\"?\")}')
" 2>/dev/null
echo ""

# 4b. iOS App Team ID (CRITICAL for App Attest)
echo "── 4b. iOS App Team ID ──"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebase.googleapis.com/v1beta1/projects/${PROJECT_ID}/iosApps/${IOS_APP_ID}" | python3 -c "
import sys,json
d=json.load(sys.stdin)
tid=d.get('teamId','')
if tid:
    print(f'  ✅ Team ID: {tid}')
else:
    print('  ❌ Team ID: NOT SET — App Attest WILL FAIL!')
    print('  Fix: curl -X PATCH ... -d '{\"teamId\":\"YOUR_TEAM_ID\"}' .../iosApps/APP_ID?updateMask=teamId')
" 2>/dev/null
echo ""

# 5. Android SHA Fingerprints (SHA-1 + SHA-256)
echo "── 5. Android SHA Fingerprints ──"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebase.googleapis.com/v1beta1/projects/${PROJECT_ID}/androidApps/${ANDROID_APP_ID}/sha" | python3 -c "
import sys,json
d=json.load(sys.stdin)
certs=d.get('certificates',[])
sha1 = [c for c in certs if c.get('certType')=='SHA_1']
sha256 = [c for c in certs if c.get('certType')=='SHA_256']
print(f'  Total: {len(certs)} ({len(sha1)} SHA-1, {len(sha256)} SHA-256)')
for cert in certs:
    print(f'  - {cert.get(\"certType\",\"?\"):8s} : {cert.get(\"shaHash\",\"?\")}')
if len(sha256) < 3:
    print(f'  ⚠️  Only {len(sha256)} SHA-256 fingerprints. Need 3: debug + upload + app-signing')
    print(f'      App Check requires SHA-256, not SHA-1')
" 2>/dev/null
echo ""

# 6. Debug Tokens
echo "── 6. Debug Tokens ──"
echo "  Android:"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_ID}/apps/${ANDROID_APP_ID}/debugTokens" | python3 -c "
import sys,json
d=json.load(sys.stdin)
tokens=d.get('debugTokens',[])
print(f'    Count: {len(tokens)}')
for t in tokens:
    print(f'    - {t.get(\"displayName\",\"unnamed\")} ({t[\"name\"].split(\"/\")[-1]})')
" 2>/dev/null
echo "  iOS:"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_ID}/apps/${IOS_APP_ID}/debugTokens" | python3 -c "
import sys,json
d=json.load(sys.stdin)
tokens=d.get('debugTokens',[])
print(f'    Count: {len(tokens)}')
for t in tokens:
    print(f'    - {t.get(\"displayName\",\"unnamed\")} ({t[\"name\"].split(\"/\")[-1]})')
" 2>/dev/null
echo ""

echo "── Audit Complete ──"

Step-by-Step Setup

Step 0: Register App for App Check

Option A: Via REST API / CLI (Preferred)

You can now configure App Check entirely via CLI:

1. Set iOS Team ID (required for App Attest):

# Check if Team ID is already set
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebase.googleapis.com/v1beta1/projects/${PROJECT_ID}/iosApps/${IOS_APP_ID}" | python3 -c "
import sys,json; d=json.load(sys.stdin); print(f'teamId: {d.get(\"teamId\",\"NOT SET\")}')"

# Set Team ID if missing
curl -X PATCH -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"YOUR_APPLE_TEAM_ID"}' \
  "https://firebase.googleapis.com/v1beta1/projects/${PROJECT_ID}/iosApps/${IOS_APP_ID}?updateMask=teamId"

2. Configure App Attest (iOS):

curl -X PATCH -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"tokenTtl":"3600s"}' \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/apps/${IOS_APP_ID}/appAttestConfig?updateMask=tokenTtl"

3. Configure DeviceCheck (iOS fallback):

curl -X PATCH -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"tokenTtl":"3600s"}' \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/apps/${IOS_APP_ID}/deviceCheckConfig?updateMask=tokenTtl"

Option B: Via Firebase Console UI

If the REST API approach doesn't fully register the app (status still shows "未註冊"):

1. Go to Firebase Console → your project → App Check → 應用程式 (Apps) tab
2. If the app's status shows "未註冊" (Not registered), click the app row to expand it
3. Select the attestation provider:
   • iOS: Select App Attest (and optionally DeviceCheck for fallback)
   • Android: Select Play Integrity
4. For iOS: Fill in your Apple Team ID (e.g. <YOUR_TEAM_ID> (10-character alphanumeric) — find it at Apple Developer → Membership)
5. Set the token TTL (default 1 hour is fine for most apps)
6. Click Save
7. Verify the status changes from "未註冊" to "已註冊" (Registered)
8. Repeat for each app (iOS, Android) that needs App Check

IAM Role Requirement: This operation requires roles/editor or roles/owner on the Firebase project. roles/firebase.viewer or even roles/firebaseappcheck.admin is NOT sufficient. Grant the required role with:

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL" --role="roles/editor"

Step 1: Enable Required APIs

# Enable App Check API
gcloud services enable firebaseappcheck.googleapis.com --project=${PROJECT_ID}

# Enable Play Integrity API (required for Android attestation)
gcloud services enable playintegrity.googleapis.com --project=${PROJECT_ID}

Step 2: Register Android SHA-256 Fingerprints

You need three SHA-256 fingerprints for Android:

List Current Fingerprints

curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebase.googleapis.com/v1beta1/projects/${PROJECT_ID}/androidApps/${ANDROID_APP_ID}/sha"

Add a SHA-256 Fingerprint

Convert the colon-separated format to lowercase hex (remove colons): 64:50:0E:EF:... → 64500eef...

curl -s -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"shaHash":"LOWERCASE_HEX_NO_COLONS","certType":"SHA_256"}' \
  "https://firebase.googleapis.com/v1beta1/projects/${PROJECT_ID}/androidApps/${ANDROID_APP_ID}/sha"

Getting All 3 SHA-256 Fingerprints

⚠️ ./gradlew signingReport prerequisite: This command requires Flutter plugin cache to exist. Run flutter pub get first, otherwise Gradle fails with Plugin directory does not exist.

⚠️ keytool locale issue: On non-English systems (e.g. Chinese locale), keytool -list -v outputs labels in the local language (e.g. 憑證指紋 instead of Certificate fingerprints). Use grep SHA or pipe through python instead of grep SHA-256.

Recommended: Direct keytool approach (locale-agnostic, no Gradle needed)

# Debug key — default Android debug keystore
keytool -list -v -keystore ~/.android/debug.keystore -storepass android 2>&1 | head -30

# Upload key — project-specific release keystore (check android/key.properties for path/password)
keytool -list -v -keystore android/app/upload-keystore.jks -storepass YOUR_PASSWORD 2>&1 | head -30

# Look for the SHA256 line (may appear as `SHA256:` or `SHA-256:` depending on locale)

Alternative: Gradle signingReport (requires pub get first)

flutter pub get  # MUST run first
cd android && ./gradlew signingReport 2>/dev/null | head -60

App Signing key (from Google Play Console)

⚠️ The Google Play Developer REST API does NOT expose the App Signing Key. Endpoints like /appSigningKey and /appIntegrity return 404. You MUST use the Play Console UI or Playwright.

Option A: Playwright (automated) Navigate to https://play.google.com/console/u/0/developers/{DEVELOPER_ID}/app-list, then:

1. Click on your app
2. Sidebar: "Test and release" (測試與發布) → "App integrity" (應用程式完整性)
3. Click "Play App Signing" (Play 應用程式簽署) setup
4. Find "App signing key certificate" section → SHA-256 fingerprint

Option B: Play Console UI (manual) Play Console → Your App → Release → Setup → App integrity → App signing key certificate → SHA-256

Convert and register:

# Convert colon-separated to lowercase hex:
echo "64:50:0E:EF:..." | tr -d ':' | tr 'A-F' 'a-f'
# → 64500eef...

Step 3: iOS App Attest Entitlement

CRITICAL: The iOS app must have the App Attest entitlement. Without it, App Attest silently fails on release builds and all iOS requests are rejected when services are ENFORCED.

Check if entitlement exists:

grep -r "appattest" ios/ --include="*.entitlements" 2>/dev/null || echo "❌ No App Attest entitlement found!"

Add the entitlement:

Option A: Create/update entitlements file manually:

Create ios/Runner/Runner.entitlements:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.devicecheck.appattest-environment</key>
    <string>production</string>
</dict>
</plist>

Then add it to Xcode project via xcodeproj gem:

require 'xcodeproj'
project = Xcodeproj::Project.open('ios/Runner.xcodeproj')
target = project.targets.find { |t| t.name == 'Runner' }
target.build_configurations.each do |config|
  config.build_settings['CODE_SIGN_ENTITLEMENTS'] = 'Runner/Runner.entitlements'
end
project.save

Option B: Use Xcode → Runner target → Signing & Capabilities → + Capability → App Attest

Step 3b: iOS DeviceCheck Private Key (REQUIRED for fallback)

CRITICAL: If you use appAttestWithDeviceCheckFallback (recommended), you must upload an Apple DeviceCheck private key (.p8) to Firebase Console. Without this key, when App Attest fails (~25% of the time), the DeviceCheck fallback also fails because Firebase has no way to validate DeviceCheck tokens. The result: you still get the same ~25% failure rate as appAttest alone.

Create the DeviceCheck Key

1. Go to Apple Developer Console → Keys
2. Click + to create a new key
3. Give it a name (e.g. Firebase DeviceCheck)
4. Check DeviceCheck capability (NOT "App Store Connect API" — that is a different key type)
5. Click Continue → Register
6. Download the .p8 file (e.g. AuthKey_ABCD1234.p8) — you can only download it once
7. Note the Key ID shown on the confirmation page

Warning: An App Store Connect API key (.p8) does NOT work for DeviceCheck. You must create a key specifically with the DeviceCheck capability checked. They are different key types even though both produce .p8 files.

Upload to Firebase via REST API

ACCESS_TOKEN=$(gcloud auth print-access-token)
PROJECT_ID="your-project-id"
IOS_APP_ID="1:xxxx:ios:xxxx"

PRIVATE_KEY=$(cat path/to/AuthKey_KEYID.p8 | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
curl -s -X PATCH \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d "{\"keyId\":\"YOUR_KEY_ID\",\"privateKey\":${PRIVATE_KEY},\"tokenTtl\":\"3600s\"}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_ID}/apps/${IOS_APP_ID}/deviceCheckConfig?updateMask=keyId,privateKey,tokenTtl"

Replace YOUR_KEY_ID with the Key ID from Apple Developer Console (e.g. ABCD1234).

Notes

• This key can be reused across all iOS apps in the same Apple Developer team — you only need one DeviceCheck key.
• Sharing DeviceCheck Keys across apps: Because DeviceCheck keys are scoped to Apple Developer team, you can reuse one key across all iOS apps in the same team. Store the .p8 file securely (e.g., 1Password or ~/.app_store_credentials/) and set env vars DEVICECHECK_KEY_ID + DEVICECHECK_KEY_PATH in a local .env (NOT committed).
• To verify the key is configured, use the audit script or check directly:

  curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/apps/${IOS_APP_ID}/deviceCheckConfig"
  

  A successful response will show keyId and tokenTtl (the privateKey is never returned).

Step 4: Check Provider Configs

Android (Play Integrity)

curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/apps/${ANDROID_APP_ID}/playIntegrityConfig"

iOS (App Attest)

curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/apps/${IOS_APP_ID}/appAttestConfig"

Step 5: Enforce Services

List All Services and Their Enforcement Status

curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/services"

Set Service to ENFORCED

curl -s -X PATCH \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"enforcementMode":"ENFORCED"}' \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/services/SERVICE_NAME?updateMask=enforcementMode"

Common Firebase Service Names

Batch Enforce Multiple Services

for SERVICE in firebaseml.googleapis.com firebasestorage.googleapis.com identitytoolkit.googleapis.com; do
  echo "Enforcing $SERVICE..."
  curl -s -X PATCH \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Content-Type: application/json" \
    -d '{"enforcementMode":"ENFORCED"}' \
    "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_NUMBER}/services/${SERVICE}?updateMask=enforcementMode"
  echo ""
done

Step 6: Debug Tokens

Debug tokens allow debug/CI builds to pass App Check when services are ENFORCED.

Generate and Register a Debug Token

# Generate a UUID token
DEBUG_TOKEN=$(python3 -c "import uuid; print(str(uuid.uuid4()))")
echo "Debug token: $DEBUG_TOKEN"

# Register for Android
curl -s -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d "{\"displayName\":\"Local Dev Mac\",\"token\":\"${DEBUG_TOKEN}\"}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_ID}/apps/${ANDROID_APP_ID}/debugTokens"

# Register for iOS
curl -s -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d "{\"displayName\":\"Local Dev Mac\",\"token\":\"${DEBUG_TOKEN}\"}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_ID}/apps/${IOS_APP_ID}/debugTokens"

List Debug Tokens

curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/projects/${PROJECT_ID}/apps/${ANDROID_APP_ID}/debugTokens"

Delete a Debug Token

curl -s -X DELETE \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://firebaseappcheck.googleapis.com/v1/TOKEN_RESOURCE_NAME"

Flutter Code Integration

IMPORTANT: Check your firebase_core version first to determine Gen 3 vs Gen 4. The API is different.

Gen 4 (firebase_core ^4.4.0, firebase_app_check ^0.4.x)

dependencies:
  firebase_app_check: ^0.4.1+4  # MUST use 0.4.x+ for new provider API

import 'package:firebase_app_check/firebase_app_check.dart';
import 'package:flutter/foundation.dart';

// After Firebase.initializeApp()
// kDebugMode is a compile-time constant — Dart tree-shakes the entire
// debug branch from release builds, so the token never leaks into production.
await FirebaseAppCheck.instance.activate(
  // Production: hardware-backed attestation
  // Debug: debug provider with pre-registered token (named param!)
  providerAndroid: kDebugMode
      ? const AndroidDebugProvider(debugToken: 'your-registered-uuid')
      : const AndroidPlayIntegrityProvider(),
  providerApple: kDebugMode
      ? const AppleDebugProvider(debugToken: 'your-registered-uuid')
      : const AppleAppAttestWithDeviceCheckFallbackProvider(),  // MUST use fallback — appAttest alone has ~25% failure rate
);

Gen 3 (firebase_core ^3.x, firebase_app_check ^0.3.x)

dependencies:
  firebase_app_check: ^0.3.2+10

import 'package:firebase_app_check/firebase_app_check.dart';
import 'package:flutter/foundation.dart';

// After Firebase.initializeApp()
await FirebaseAppCheck.instance.activate(
  // Gen 3 uses enum values, not class constructors
  appleProvider: kDebugMode
      ? AppleProvider.debug
      : AppleProvider.appAttestWithDeviceCheckFallback,  // MUST use fallback — appAttest alone has ~25% failure rate
  androidProvider: kDebugMode
      ? AndroidProvider.debug
      : AndroidProvider.playIntegrity,
);

Sideloaded Release Builds (USE_DEBUG_APPCHECK pattern)

⚠️ PlayIntegrity inherently FAILS on sideloaded release APKs — it only works for apps installed from Google Play. This means adb install app-release.apk will always fail PlayIntegrity attestation, even with correct SHA-256 fingerprints registered.

The fix is a --dart-define flag that lets you control the provider independently of kDebugMode:

Flutter code (Gen 3):

// USE_DEBUG_APPCHECK=true in .env → forces debug provider even on release builds
const useDebugAppCheck = bool.fromEnvironment('USE_DEBUG_APPCHECK');
await FirebaseAppCheck.instance.activate(
  androidProvider: (kDebugMode || useDebugAppCheck)
      ? AndroidProvider.debug
      : AndroidProvider.playIntegrity,
  appleProvider: (kDebugMode || useDebugAppCheck)
      ? AppleProvider.debug
      : AppleProvider.appAttestWithDeviceCheckFallback,
);

Dual .env file pattern:

Key: Debug provider still requires a registered debug token. Each fresh app install generates a new token (check logcat). Register it via the Debug Tokens REST API.

Fresh install = new debug token: When you uninstall + reinstall a sideloaded release APK, the debug provider generates a NEW UUID. You must register it again. The old token becomes invalid.

Common Gen 3 mistake: Using AppleProvider.appAttest alone. It has ~25% failure rate in production. Always use AppleProvider.appAttestWithDeviceCheckFallback.

OPTIONAL: Verify token in debug mode (both Gen 3 & 4)

if (kDebugMode) {
  FirebaseAppCheck.instance
      .getToken(true)
      .timeout(const Duration(seconds: 10))
      .then((token) {
        debugPrint('[AppCheck] getToken ok=${token != null}');
      })
      .catchError((Object e) {
        debugPrint('[AppCheck] getToken failed: $e');
      });
}

Firebase AI Integration

Gen 4 (firebase_ai ^3.7.0) — MUST pass appCheck explicitly

final model = FirebaseAI.googleAI(
  appCheck: FirebaseAppCheck.instance,  // Required in Gen 4!
).generativeModel(
  model: 'gemini-2.5-flash-lite',
  // ...
);

Without appCheck: FirebaseAppCheck.instance, the SDK won't attach App Check tokens to requests and firebasevertexai.googleapis.com will reject them.

Gen 3 (firebase_ai ^2.x) — MUST also pass appCheck explicitly

// Gen 3: FirebaseAI.googleAI() ALSO accepts and REQUIRES appCheck parameter
// Without it, App Check tokens are NOT attached to AI requests
// This causes "Firebase App Check token is invalid" errors when firebaseml is ENFORCED
final model = FirebaseAI.googleAI(
  appCheck: FirebaseAppCheck.instance,  // REQUIRED! Not auto-attached in Gen 3
).generativeModel(
  model: 'gemini-2.5-flash-lite',
  // ...
);

⚠️ Critical Gen 3 Gotcha: The appCheck parameter is optional in FirebaseAI.googleAI() — if omitted, it defaults to null and no App Check token will be attached to AI requests. When firebaseml.googleapis.com is ENFORCED, this causes all requests to fail with "Firebase App Check token is invalid". The getToken() call may succeed locally, but the token is never sent to the server.

NOTE: firebasevertexai.googleapis.com ALWAYS requires valid App Check tokens — it cannot be unenforced via App Check service configuration (both Gen 3 and Gen 4).

Complete Setup Checklist

Server-Side (Firebase Console / CLI)

• CRITICAL: Register iOS and Android apps in Firebase Console UI (App Check → 應用程式 tab → Not just REST API!)
• gcloud services enable firebaseappcheck.googleapis.com
• gcloud services enable playintegrity.googleapis.com
• Add 3 Android SHA-256 fingerprints (debug + upload + App Signing)
• Set desired services to ENFORCED (especially firebaseml.googleapis.com)
• Register debug tokens for dev/CI environments

Client-Side (Flutter)

• Check Firebase generation (pubspec.lock → firebase_core version) to determine Gen 3 vs Gen 4 API
• Gen 4: firebase_app_check ^0.4.x + new AndroidDebugProvider() / AppleAppAttestProvider() API
• Gen 3: firebase_app_check ^0.3.x + old AndroidProvider.debug / AppleProvider.appAttest enum API
• Gen 4 only: Pass appCheck: FirebaseAppCheck.instance to FirebaseAI.googleAI() (Gen 3 auto-attaches)
• iOS: Add com.apple.developer.devicecheck.appattest-environment = production to entitlements
• iOS: Upload Apple DeviceCheck private key (.p8) to Firebase Console (required for appAttestWithDeviceCheckFallback)
• Test: Debug build passes App Check (debug provider + registered token)
• Test: Release build passes App Check (Play Integrity / App Attest)

Firebase Package Version Compatibility

All Firebase packages must be on the same generation. Mixing versions causes dependency conflicts.

If you upgrade ONE Firebase package, you likely need to upgrade ALL of them.

Common Mistakes

Related skills

• firebase-flutter-setup → firebase-appcheck-manager — complete Firebase setup before configuring App Check.
• firebase-ai-logic — use alongside firebase-appcheck-manager for secure AI Logic deployments; AppCheck attestation protects backend API calls.