Skip to content

App Check reference

At a glance

  • Providers (before core.configure()): use_debug_provider(), use_device_check_provider(), use_app_attest_provider(), use_recaptcha_provider(site_key), use_custom_provider(provider); running_in_simulator(); initialize_debug_appcheck() (0.1 name)
  • AppCheckProvider (get_token(callback), get_limited_use_token(callback)), AppCheckToken(token, expiration_date)
  • AppCheck.app_check(): token(cb, force_refresh), limited_use_token(cb), add_token_listener(listener) → AppCheckTokenListener, is_token_auto_refresh_enabled, debug_token()
  • AppCheckErrorCode, DEBUG_TOKEN_ENVIRONMENT_VARIABLE

pyios_firebase.app_check

Firebase App Check: prove requests come from your real app.

Choose a provider before core.configure()::

from pyios_firebase import app_check, core

if app_check.running_in_simulator():
    app_check.use_debug_provider()      # register the debug token in the console
else:
    app_check.use_app_attest_provider() # or use_device_check_provider()
core.configure()

Firestore, Functions, Storage, Auth and the other Firebase SDKs then attach App Check tokens by themselves. For your own backend, get a token with AppCheck.app_check().token(...).

Needs the FirebaseAppCheck framework. App Attest also needs the App Attest capability (com.apple.developer.devicecheck.appattest-environment).

Classes:

Name Description
AppCheckErrorCode

The error.code values of App Check errors (FIRAppCheckErrorCode).

AppCheckToken

An App Check token.

AppCheckProvider

A custom App Check provider, written in Python: for example tokens from

AppCheckTokenListener

Given back by AppCheck.add_token_listener. Call remove() to stop.

AppCheck

App Check for the default Firebase app. Get it with AppCheck.app_check().

Functions:

Name Description
running_in_simulator

True in the iOS Simulator, where App Attest and DeviceCheck do not work

use_debug_provider

Use the debug provider: for the Simulator, development and CI.

initialize_debug_appcheck

The 0.1 name of use_debug_provider.

use_device_check_provider

Use Apple's DeviceCheck (the default provider). Works on real devices

use_app_attest_provider

Use Apple's App Attest: the strongest attestation, on real devices with

use_recaptcha_provider

Use reCAPTCHA Enterprise. Needs the reCAPTCHA Enterprise SDK in the app.

use_custom_provider

Use a custom provider written in Python.

Attributes:

Name Type Description
APP_CHECK_ERROR_DOMAIN Final

The error.domain of App Check errors.

DEBUG_TOKEN_ENVIRONMENT_VARIABLE Final

Set it (for example in CI) to make the debug provider use that token

TokenCallback

(token, None) or (None, error_message).

APP_CHECK_ERROR_DOMAIN module-attribute

APP_CHECK_ERROR_DOMAIN: Final = 'com.firebase.appCheck'

The error.domain of App Check errors.

DEBUG_TOKEN_ENVIRONMENT_VARIABLE module-attribute

DEBUG_TOKEN_ENVIRONMENT_VARIABLE: Final = (
    "FIRAAppCheckDebugToken"
)

Set it (for example in CI) to make the debug provider use that token instead of a random one. AppCheckDebugToken also works.

TokenCallback module-attribute

TokenCallback = Callable[
    [AppCheckToken | None, str | None], None
]

(token, None) or (None, error_message).

AppCheckErrorCode

The error.code values of App Check errors (FIRAppCheckErrorCode).

Attributes:

Name Type Description
SERVER_UNREACHABLE Final

No network, or the App Check server did not answer.

INVALID_CONFIGURATION Final

The provider or the Firebase project is not set up right.

KEYCHAIN Final

The keychain could not store the token.

UNSUPPORTED Final

The provider does not work here (for example App Attest in the Simulator).

SERVER_UNREACHABLE class-attribute instance-attribute

SERVER_UNREACHABLE: Final = 1

No network, or the App Check server did not answer.

INVALID_CONFIGURATION class-attribute instance-attribute

INVALID_CONFIGURATION: Final = 2

The provider or the Firebase project is not set up right.

KEYCHAIN class-attribute instance-attribute

KEYCHAIN: Final = 3

The keychain could not store the token.

UNSUPPORTED class-attribute instance-attribute

UNSUPPORTED: Final = 4

The provider does not work here (for example App Attest in the Simulator).

AppCheckToken dataclass

AppCheckToken(token: str, expiration_date: datetime)

An App Check token.

Methods:

Name Description
from_native

Copy a native FIRAppCheckToken.

to_native

Make the native FIRAppCheckToken.

Attributes:

Name Type Description
token str

The token: send it in the X-Firebase-AppCheck header to your backend.

expiration_date datetime

When it expires (UTC).

token instance-attribute

token: str

The token: send it in the X-Firebase-AppCheck header to your backend.

expiration_date instance-attribute

expiration_date: datetime

When it expires (UTC).

from_native classmethod

from_native(native: ObjCObject) -> AppCheckToken

Copy a native FIRAppCheckToken.

Parameters:

Name Type Description Default
native ObjCObject

the FIRAppCheckToken.

required

to_native

to_native() -> ObjCObject

Make the native FIRAppCheckToken.

AppCheckProvider

Bases: ABC

A custom App Check provider, written in Python: for example tokens from your own attestation service. Pass it to use_custom_provider.

::

class MyProvider(AppCheckProvider):
    def get_token(self, callback):
        my_service.fetch(lambda token, expires: callback(AppCheckToken(token, expires), None))

Firebase may call these methods on a background thread.

Methods:

Name Description
get_token

Make a token, then call callback exactly once.

get_limited_use_token

Make a single-use token (for replay protection). By default, the

get_token abstractmethod

get_token(callback: TokenCallback) -> None

Make a token, then call callback exactly once.

Parameters:

Name Type Description Default
callback TokenCallback

call it with (AppCheckToken, None), or (None, "what went wrong").

required

get_limited_use_token

get_limited_use_token(callback: TokenCallback) -> None

Make a single-use token (for replay protection). By default, the same as get_token.

Parameters:

Name Type Description Default
callback TokenCallback

call it with (AppCheckToken, None), or (None, "what went wrong").

required

PyAppCheckProviderBridge

Bases: NSObject

Lets Firebase call a Python AppCheckProvider.

Rubicon reads these methods' annotations to build their Objective-C signatures: parameters must be annotated with ctypes types.

Methods:

Name Description
getTokenWithCompletion_

Firebase asks for a token.

getLimitedUseTokenWithCompletion_

Firebase asks for a limited-use token.

getTokenWithCompletion_

getTokenWithCompletion_(handler: objc_block) -> None

Firebase asks for a token.

getLimitedUseTokenWithCompletion_

getLimitedUseTokenWithCompletion_(
    handler: objc_block,
) -> None

Firebase asks for a limited-use token.

PyAppCheckProviderFactory

Bases: NSObject

Lets Firebase ask Python for a provider for each Firebase app.

Methods:

Name Description
createProviderWithApp_

Firebase asks for the provider of app.

createProviderWithApp_

createProviderWithApp_(app: objc_id) -> objc_id

Firebase asks for the provider of app.

AppCheckTokenListener

AppCheckTokenListener(
    observer: ObjCObject, release: Callable[[], None]
)

Given back by AppCheck.add_token_listener. Call remove() to stop.

Parameters:

Name Type Description Default
observer ObjCObject

the native NSNotificationCenter observer.

required
release Callable[[], None]

releases the listener's callback block.

required

Methods:

Name Description
remove

Stop the updates. Safe to call more than once.

remove

remove() -> None

Stop the updates. Safe to call more than once.

AppCheck

AppCheck(native: ObjCObject)

App Check for the default Firebase app. Get it with AppCheck.app_check().

Parameters:

Name Type Description Default
native ObjCObject

the native FIRAppCheck.

required

Methods:

Name Description
app_check

The shared instance (after core.configure()).

token

Get an App Check token, for example to call your own backend.

limited_use_token

Get a limited-use (single-use) token, for backends with replay

add_token_listener

Listen for new App Check tokens (each refresh), on the main thread.

debug_token

The debug provider's token: the DEBUG_TOKEN_ENVIRONMENT_VARIABLE

Attributes:

Name Type Description
native ObjCObject

The FIRAppCheck.

is_token_auto_refresh_enabled bool

Whether App Check refreshes the token before it expires (the default

native property

native: ObjCObject

The FIRAppCheck.

is_token_auto_refresh_enabled property writable

is_token_auto_refresh_enabled: bool

Whether App Check refreshes the token before it expires (the default comes from FirebaseAppCheckTokenAutoRefreshEnabled in Info.plist, else Firebase's data collection setting).

app_check classmethod

app_check() -> AppCheck

The shared instance (after core.configure()).

token

token(
    callback: Callable[
        [AppCheckToken | None, FirebaseError | None], None
    ],
    force_refresh: bool = False,
) -> None

Get an App Check token, for example to call your own backend.

The token is cached, also across app launches, until it is about to expire: the provider is only asked again then, or with force_refresh.

Parameters:

Name Type Description Default
callback Callable[[AppCheckToken | None, FirebaseError | None], None]

gets (AppCheckToken, None), or (None, error).

required
force_refresh bool

get a new token even if the cached one is valid.

False

limited_use_token

limited_use_token(
    callback: Callable[
        [AppCheckToken | None, FirebaseError | None], None
    ],
) -> None

Get a limited-use (single-use) token, for backends with replay protection. It is not cached and does not affect token.

Parameters:

Name Type Description Default
callback Callable[[AppCheckToken | None, FirebaseError | None], None]

gets (AppCheckToken, None), or (None, error).

required

add_token_listener

add_token_listener(
    listener: Callable[[str], None],
) -> AppCheckTokenListener

Listen for new App Check tokens (each refresh), on the main thread.

Parameters:

Name Type Description Default
listener Callable[[str], None]

gets the new token string.

required

Returns:

Type Description
AppCheckTokenListener

An AppCheckTokenListener. Call .remove() to stop.

debug_token staticmethod

debug_token() -> str

The debug provider's token: the DEBUG_TOKEN_ENVIRONMENT_VARIABLE token if set, else this device's local one. Register it in the Firebase console. Works whichever provider is in use (after core.configure()).

Returns:

Type Description
str

The token.

running_in_simulator

running_in_simulator() -> bool

True in the iOS Simulator, where App Attest and DeviceCheck do not work (use the debug provider there).

use_debug_provider

use_debug_provider() -> None

Use the debug provider: for the Simulator, development and CI.

On first run it prints Firebase App Check debug token: '...' in the Xcode console; add that token in the Firebase console (App Check, your app, Manage debug tokens). In CI, set DEBUG_TOKEN_ENVIRONMENT_VARIABLE to a registered token. Never ship it: anyone with the token passes App Check.

Raises:

Type Description
RuntimeError

core.configure() was already called.

initialize_debug_appcheck

initialize_debug_appcheck() -> None

The 0.1 name of use_debug_provider.

use_device_check_provider

use_device_check_provider() -> None

Use Apple's DeviceCheck (the default provider). Works on real devices with iOS 11+; not in the Simulator.

Raises:

Type Description
RuntimeError

core.configure() was already called.

use_app_attest_provider

use_app_attest_provider() -> None

Use Apple's App Attest: the strongest attestation, on real devices with iOS 14+. Needs the App Attest capability; not in the Simulator.

Raises:

Type Description
RuntimeError

core.configure() was already called.

use_recaptcha_provider

use_recaptcha_provider(site_key: str) -> None

Use reCAPTCHA Enterprise. Needs the reCAPTCHA Enterprise SDK in the app.

Parameters:

Name Type Description Default
site_key str

the reCAPTCHA Enterprise site key for iOS.

required

Raises:

Type Description
RuntimeError

core.configure() was already called.

use_custom_provider

use_custom_provider(
    provider: AppCheckProvider
    | Callable[[ObjCObject], AppCheckProvider],
) -> None

Use a custom provider written in Python.

Parameters:

Name Type Description Default
provider AppCheckProvider | Callable[[ObjCObject], AppCheckProvider]

an AppCheckProvider for every Firebase app, or a function that gets the native FIRApp and returns the provider for it.

required

Raises:

Type Description
RuntimeError

core.configure() was already called.