Firexport / Blog

Los errores de App Check se producen en uno de dos pasos: cuando la app obtiene un token de su proveedor de certificación (Play Integrity, App Attest, reCAPTCHA) o cuando un servicio de Firebase verifica ese token. Si falla el primero, también falla el segundo, así que no te quedes en el error del servicio: busca primero el error del intercambio de tokens y corrige los valores registrados de tu plataforma. Los emuladores, los simuladores y localhost no pueden superar la certificación de por sí, así que usan un token de depuración.

Encontrar por el mensaje el paso que falló

Si no se obtiene el token, las solicitudes al servicio no llevan ningún token válido (el SDK web adjunta en su lugar un token ficticio). Por eso, aunque veas un error del lado del servicio, comprueba primero si en los logs aparece también un error al obtener el token. Tras un fallo, el SDK pospone los reintentos: en la web, 24 horas después de un 403 o un 404; en Android y Apple, 24 horas después de un 400 o un 404, y con los demás errores, hasta 4 horas. Ese estado solo se guarda en memoria, así que, después de corregir la configuración, reinicia la app o vuelve a cargar la página antes de comprobarlo.

Token de depuración durante el desarrollo

Los emuladores y los simuladores no cuentan como dispositivos válidos, y las compilaciones de depuración que no están en Google Play no superan Play Integrity. Por norma, las claves de reCAPTCHA no incluyen localhost. En estos entornos, activa el proveedor de depuración y registra en la consola el token que aparece en los logs.

1. Activa el proveedor de depuración solo en las compilaciones de desarrollo.

   // Android (Kotlin): com.google.firebase:firebase-appcheck-debug
   Firebase.appCheck.installAppCheckProviderFactory(
       if (BuildConfig.DEBUG) DebugAppCheckProviderFactory.getInstance()
       else PlayIntegrityAppCheckProviderFactory.getInstance(),
   )
   
   // iOS (Swift): before FirebaseApp.configure()
   #if DEBUG
   AppCheck.setAppCheckProviderFactory(AppCheckDebugProviderFactory())
   #endif
   
   // Web: before initializeAppCheck(), in development builds only
   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   
   // Flutter (firebase_app_check 0.5+)
   await FirebaseAppCheck.instance.activate(
     providerAndroid: kDebugMode
         ? const AndroidDebugProvider()
         : const AndroidPlayIntegrityProvider(),
     providerApple: kDebugMode
         ? const AppleDebugProvider()
         : const AppleAppAttestWithDeviceCheckFallbackProvider(),
   );

2. Ejecuta la app y busca el token de depuración en los logs. Los SDK actuales lo imprimen con el formato Firebase App Check debug token: <UUID> (en Android, en logcat; en Apple, en la consola de Xcode; en la web, en la consola del navegador).
3. Registra el token. En la consola de Firebase, abre la pestaña Apps de App Check y, en el menú ⋮ de la app, elige Administrar tokens de depuración (Manage debug tokens). Puedes registrar hasta 20 por app.

• Los tokens cambian. Se crea uno nuevo en Android si borras los datos de la app o la reinstalas; en Apple, si la reinstalas, y en la web, si usas otro perfil del navegador o borras los datos del sitio. El token nuevo hay que volver a registrarlo.
• En CI, pasa un token que ya hayas registrado. En la web se usa la cadena del token en self.FIREBASE_APPCHECK_DEBUG_TOKEN; en Android, el argumento de instrumentación firebaseAppCheckDebugSecret; en Apple, la variable de entorno del esquema AppCheckDebugToken, y en Flutter, el parámetro debugToken.
• Trata el token como una contraseña. No lo subas al repositorio, y deja el proveedor de depuración y el token fuera de las compilaciones de producción.

Causas por plataforma

Android (Play Integrity)

Apple (App Attest, DeviceCheck)

Web (reCAPTCHA)

AI Logic: aplicación automática desde el 2 de noviembre de 2026

Desde el 2 de noviembre de 2026, Firebase aplica App Check automáticamente a Firebase AI Logic en los proyectos que no lo aplicaban. Las solicitudes sin un token válido se bloquean, y lo mismo pasa con las versiones de la app publicadas sin App Check. Hay dos errores de AI Logic que mencionan App Check.

403 PERMISSION_DENIED: To access this model, you must enforce
Firebase App Check.

403 PERMISSION_DENIED: Firebase AI Logic has been deactivated in this
project. To resume using Firebase AI Logic, you must enforce Firebase
App Check.

• El primero aparece cuando se llama sin un token de App Check válido a un modelo del que se abusa a menudo. Configura App Check y aplícalo. Durante el desarrollo, usa el proveedor de depuración.
• El segundo aparece cuando el proyecto se consideró inactivo y no aplica App Check. Si ya lo aplicas y aun así aparece, revisa la protección contra repeticiones (replay protection): si está activada, también en el modo Monitor only, solo se aceptan los tokens de uso limitado (limited-use tokens).

Si todavía hay usuarios con versiones sin App Check, puedes posponer la aplicación forzosa. Basta con cambiar la fecha del selector Aplicación (Enforces) en la fila de Firebase AI Logic de la pestaña APIs de App Check; el 21 de enero de 2027 es la última fecha posible. Si la fila ya dice Aplicada (Enforced), para levantarla tienes que cambiar la fecha y, después, en Configurar (Set up) de esa fila, poner la Protección de referencia (Baseline protection) en Unenforced (monitoring only) y la protección contra repeticiones en Disabled. Google no lo recomienda, así que publica antes de esa fecha una versión con App Check.

Antes de aplicarlo a otros servicios

• Mira primero las métricas. La pestaña APIs de App Check divide las solicitudes de cada servicio en verificadas (Verified), de cliente desactualizado (Outdated client, sin token), de origen desconocido (Unknown origin) y no válidas (Invalid). Con App Check aplicado, solo pasan las solicitudes verificadas, así que aplícalo cuando casi todas las solicitudes recientes estén verificadas.
• Las versiones antiguas de la app quedan bloqueadas. Las versiones sin el SDK de App Check ven rechazadas sus solicitudes en cuanto lo aplicas.
• Tarda hasta 15 minutos en surtir efecto. No juzgues el resultado justo después de activar la aplicación forzosa.
• En Cloud Functions, App Check solo se puede aplicar a las funciones que admiten llamadas. Hay que agregar enforceAppCheck: true y volver a desplegar para que surta efecto. Las funciones onRequest quedan fuera de la aplicación forzosa de App Check, así que verifica el token tú mismo con el Admin SDK.

Fuentes

• Descripción general de App Check, habilitar la aplicación forzosa, supervisar las métricas, límite de tokens de depuración (REST)
• Proveedor de Play Integrity, cuota de Play Integrity, proveedor de depuración para Android
• Proveedor de App Attest, proveedor de DeviceCheck, proveedor de depuración para Apple, entorno de App Attest (Apple), dónde se puede usar App Attest (Apple)
• Proveedor de reCAPTCHA Enterprise, proveedor de reCAPTCHA v3, crear una clave de reCAPTCHA, proveedor de depuración para la web
• Proveedor de depuración para Flutter, activate() de firebase_app_check
• App Check para AI Logic, códigos de error de AI Logic, App Check para Cloud Functions, verificar tokens en tu propio backend
• Código fuente de los SDK: límite de reintentos en la web, token ficticio en la web, rechazo de Storage, mensaje de error de Android, reintentos en Android, reintentos en Apple, rechazo de las funciones que admiten llamadas