Skip to content

Device integrity

In Cloud mode the SDK can prove to Beekon Cloud that it runs inside a genuine copy of your app on a real device: hardware key attestation on Android, Apple App Attest on iOS. Every stored location records the result in its trust_tier. Custom and local modes don’t attest.

Requires SDK 0.6.0 or later, on Android and iOS and in the Flutter and React Native wrappers. Installs on SDK 0.5.0 and earlier never attest, so their locations are unverified.

trust_tierMeans
attestedThe upload came from an install that proved it is your app, signed with a certificate or by a team you registered, on a real device.
unverifiedAnything else: the install hasn’t attested yet, can’t, or failed. Also every location sent from your server through Ingest.

verified is reserved and not assigned today. The tier is a label: it doesn’t change admission, metering, geofences or anything else, unless you require attestation. It is independent of is_mock.

  • Each install has an install id that every token request carries.
  • When Beekon Cloud asks for it, the SDK attests in the background: a single-use challenge from the server, then a new per-install key bound to it: on Android the key’s certificate chain from the phone’s secure hardware (hardware key attestation), on iOS an App Attest request. After that, each token request is signed with that key.
  • At most once a day, whatever the outcome, and again about every 30 days. Tracking, sync and the first token never wait for it.
  • A device that can’t attest stays unverified and keeps working: rooted or bootloader-unlocked Android phones, custom ROMs, Android emulators, phones whose key store is software only or not certified by Google, iOS simulators and devices without App Attest.

The install id and the device key stay out of backups and device-to-device transfer, so a phone restored from a backup starts as a new install instead of a copy of the old one.

Android attests with hardware key attestation, and it needs no Google setup: no Google Cloud project, Play Console API access or Play Integrity quota. The SDK generates the device key in the phone’s secure hardware (StrongBox when the phone has it, otherwise the TEE) and sends the key’s certificate chain, which the hardware signs up to Google’s attestation root. Beekon Cloud checks it offline.

What you do need is to register your app under App integrity: its package name and the Play App Signing certificate SHA-256, plus the SHA-256 of any other signing certificate used for builds that should attest. Until it is listed, no Android install of it can attest.

Beekon Cloud checks, and labels the install attested only when all of these pass:

  • The chain ends at one of Google’s hardware attestation roots, and none of its certificates is on Google’s revocation list.
  • The key and the attestation come from the phone’s secure hardware, not a software key store.
  • The key was made for this install and this challenge.
  • The bootloader is locked and the phone booted the verified, manufacturer-signed system.
  • The app that asked for the key has a registered package name, and is signed with a certificate registered for that package.

So rooted or bootloader-unlocked phones, custom ROMs and emulators stay unverified, and so do phones whose chain doesn’t reach a Google root.

What it doesn’t check:

  • Where the app came from. It proves the real app, signed with your certificate, runs on a real phone. It doesn’t prove the app was installed from Google Play.
  • The phone’s risk. There is no Play Integrity-style device verdict. The OS security patch level is recorded, and judged only when you set a minimum security patch.
  • A leaked attestation key. A phone whose attestation key leaked can pass until Google revokes the key.
PlatformWhat you add
AndroidNothing in the app and no Google setup. Your own backup rules merge as they are (Android: backup rules). Register the app in the console’s Apps tab.
iOSThe App Attest capability. See iOS: App Attest capability.
Flutter, React NativeThe same as Android and iOS, in the host app. There is no Dart or JavaScript API for attestation.

In the console, the project’s Apps tab (under Developers, next to API keys) lists the project’s Android and iOS apps, up to 10 for each platform. Owners and admins can add, edit and remove them; members see the list.

Add app asks for the platform and then only the app’s id, with an optional Nickname (up to 60 characters, shown in the console only):

  • Android: the Package name (the applicationId in your app’s build.gradle).
  • iOS: the Bundle ID.

An app’s devices can attest once its Attestation details are added, in the same dialog or later from the app’s row:

  • Android: one to five Signing certificates SHA-256: the Play App Signing certificate, from Play Console → Test and release → App integrity → App signing (the app signing key, not the upload key), and any other certificate that builds which should attest are signed with (sideloaded, internal-store or debug builds). Android devices attest with hardware key attestation; there is nothing to set up with Google.
  • iOS: the App ID prefix (10 capital letters and digits, usually your Team ID) and the Environment: Production for App Store, TestFlight, ad-hoc and Enterprise builds, Development only for development builds. App Attest issues development and production keys separately.

Each row shows two chips:

ChipWhat it says
Attestation1 certificate (or more) for an Android app, the App ID prefix and environment for an iOS app, once it can attest. Needs SHA-256 or Needs Team ID, with Add, while it can’t: its devices stay unverified until then. Not available where the project’s region can’t verify devices.
SDK licenceCovered when the app’s id is in the organisation’s SDK licence key, or Covered by its base id for a build ending in one of the key’s suffixes (.dev, .debug, .staging, .qa and .test). No key yet while the licence lists the app but no key has been made, and Licence revoked: no key is issued after a revocation. Not covered, with Add, which adds the id to the licence. Shown to owners and admins only, and not on a server that issues no licence.

Removing an app, removing a certificate, or changing an app’s package name, bundle ID, App ID prefix or environment asks the devices attested under it to verify again. Adding the first certificate or the App ID prefix, or changing a nickname, affects no device. Removing an app here leaves its id on the SDK licence, which is organisation-wide.

Project settings → App integrity sums the apps up, for example 3 apps · 2 ready for attestation, with Manage apps.

On a deployment without attestation, App integrity says Device attestation isn’t available on this deployment. and the Apps tab says Apps aren’t available on this deployment.

Require attestation, in Project settings → App integrity (owners and admins), is off by default. It can be turned on once at least one app is ready for attestation; until then App integrity says so, with Go to Apps. While it is on, the project keeps at least one app ready: removing the last one, or removing its last certificate or its App ID prefix, is refused until you turn Require attestation off. Off, every device can upload, and locations from devices that haven’t verified are labelled unverified. On, Beekon Cloud refuses uploads from devices that haven’t verified with 403 {"error":"attestation_required"}. That includes Android devices that fail the hardware checks (unlocked bootloader, custom ROMs, software-only key stores), builds signed with a certificate you haven’t registered, iPhones on iOS 13, emulators and simulators.

A refused device keeps its locations and sends them once it verifies; it doesn’t delete them and doesn’t pause sync. Remote config, device state and log uploads stay open, so a refused device can still be configured, sent commands and diagnosed.

Minimum security patch, under Android in Project settings → App integrity (owners and admins), is Off by default, or 3 months, 6 months, 12 months or 24 months. The setting appears once the project has an Android app. When it is on, an Android phone whose last security patch is older than that, or that doesn’t report a patch level, fails verification: it gets no new attestation, and its locations become unverified once its earlier attestation expires. That includes phones their maker no longer updates. The months count from the current month: with 6 months in November 2026, a May 2026 patch passes and an April 2026 one fails. A phone that fails tries again after 7 days, so one that installs its update by then attests. iPhones aren’t affected.

The console asks you to confirm before it turns the setting on. With Require attestation on as well, a phone that fails stops uploading once its earlier attestation expires.

A device’s page shows its Attestation: Attested, Not attested, Revoked or Denied, with the platform, the Method it attested with (Hardware key attestation, Play Integrity or App Attest), when it attested and when that expires. For hardware key attestation, Key says how the phone got its attestation key: Remote-provisioned (issued by Google over the network, on Android 12 and later; there is no long-lived key to leak) or Factory (installed when the phone was made; a leaked factory key can pass until Google revokes it). The line is absent when Beekon can’t tell. Neither line changes the tier. Owners and admins can:

  • Re-verify: the device is asked to verify again. Until it does, its locations are labelled unverified.
  • Deny: locations from this install are labelled unverified, even if it passes verification.
  • Clear (when denied or revoked): deletes the device’s attestation record.