Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

App attestation lets Synheart confirm that traffic comes from your real, unmodified build on a normal device, not from emulators, repackaged binaries, or scripted clients. The platform supports: Both platforms follow the same client flow: the SDK requests a one-time challenge, asks the OS for an attestation over that challenge, and registers the attested device with Synheart. You configure each App in the platform dashboard once; the SDKs handle the runtime path.
The Synheart app_id (shown on the App in the platform dashboard) is the platform’s identifier for that App record — a short code like app_focus_and_kB8mPx. Your Android packageName and iOS bundle ID are separate values you also configure on the App. Don’t conflate them: Play Console steps below refer to your Play listing’s packageName, not the platform app_id.

​
Configure attestation in the dashboard

For each App in the platform dashboard, open App settings and fill in the attestation block. Fields differ by OS:
OSRequiredOptional
Androidbundle_id (Android packageName), google_project_id (GCP project linked to your Play Console listing)allow_emulator — accept emulator-class devices in dev
iOSbundle_id (iOS bundle ID), team_id (Apple Developer Team ID)production — uncheck to accept App Attest sandbox attestations during development
Both platforms also accept a per-app dev_mode flag that relaxes verdict requirements for development builds. Leave it off for production.

​
Android — Play Integrity setup

You complete Play Console and Google Cloud steps once per Play developer account. Synheart never runs your app for you; we only verify Play Integrity tokens using the service account you authorize in step 4.

​
Before you start

You need:
  • A Google Play Developer account and access to Play Console for the app you want attested.
  • The app created in Play Console (a draft or any release track is enough to attach permissions).
  • Permission to invite users and manage API access in Play Console (admin or equivalent).

​
Steps

1

Copy the Synheart service account email

Use this exact address when you invite Google Play access. It is Synheart’s read-only identity for integrity checks — not a personal account.
platform-integrity-check1@platform-integrity-check.iam.gserviceaccount.com
2

Link a Google Cloud project to Play Console

Play Integrity is tied to the Cloud project linked to your Play developer account.
  1. Open Google Play Console.
  2. Go to Setup → API access (or search API access in the sidebar).
  3. If you see Link or Create new project, complete that flow so Play Console shows a linked Google Cloud project.
You will enable the Integrity API on this linked project in the next step.
3

Enable the Play Integrity API in Google Cloud

Enable the API for the same Cloud project shown under Play Console → Setup → API access.Open Play Integrity API in Google Cloud ConsoleChoose the linked project from the project picker, then click Enable. If the button already says Manage, the API is on — you can continue.
4

Invite the Synheart service account in Play Console

Grant Synheart’s service account read-only visibility to the app(s) you want verified.
  1. In Play Console, open Users and permissions → Invite new users (sometimes under Setup → Users and permissions).
  2. Paste platform-integrity-check1@platform-integrity-check.iam.gserviceaccount.com into Email address.
  3. Under App permissions, choose Add app and select every application Synheart should attest.
  4. Under Account permissions, enable View app information and download bulk reports (read-only). Do not grant release, financial, or user-data permissions — they are not required.
  5. Send the invitation (Invite user / Save).
Access usually propagates within a short time; if checks still fail after an hour, contact support with your Play packageName, the Synheart app_id, and the time you sent the invite.
5

Set the App's attestation fields in the platform dashboard

On the matching App in the platform dashboard, set:
  • bundle_id — your Android packageName (for example com.example.focus).
  • google_project_id — the GCP project ID you linked in step 2.
  • allow_emulator — leave off for production; turn on only for development builds you want to test on an emulator.

​
What gets enforced

Synheart calls decodeIntegrityToken server-side and checks:
  • Real device. Tokens from emulators or virtual devices are rejected unless allow_emulator is on.
  • Recognized app. The build must match a Play-distributed version of your packageName. Sideloaded or repackaged builds fail.
  • Token freshness. Tokens older than five minutes are rejected to prevent replay.
The service account permission above is read-only; it cannot publish releases, change store listings, view financials, or access end-user personal data in Play.

​
iOS — App Attest setup

iOS attestation uses Apple App Attest, which is built into iOS 14+. There is no Apple-side invite step: the OS attests directly to Apple, and Synheart verifies the resulting attestation object.

​
Before you start

You need:
  • An Apple Developer account with the app’s bundle ID provisioned.
  • iOS 14 or later on a real device — App Attest is not available in the iOS Simulator.

​
Steps

1

Note your Apple Team ID and bundle ID

Both are visible at developer.apple.com/account under Membership (Team ID) and Identifiers (bundle ID).
2

Set the App's attestation fields in the platform dashboard

On the matching App in the platform dashboard, set:
  • bundle_id — your iOS bundle ID (for example com.example.focus).
  • team_id — your 10-character Apple Developer Team ID.
  • production — check for App Store / TestFlight builds. Uncheck only for development builds attested against Apple’s sandbox environment.
3

Build with the App Attest entitlement

Add the com.apple.developer.devicecheck.appattest-environment entitlement (production or development) to your app’s entitlements plist. Match it to the dashboard production toggle.

​
What gets enforced

The Synheart verifier checks:
  • Apple-signed certificate chain. The attestation must chain to Apple’s App Attest root.
  • Bundle ID + Team ID. The relying party hash inside the attestation must match team_id + bundle_id configured on the App.
  • Challenge nonce. The attestation must cover the exact challenge nonce Synheart issued (5-minute TTL).
  • Sandbox vs production. The attestation environment must match the production flag on the App.

​
Client flow

Both platforms follow the same three-step pattern; the SDKs implement this for you:
  1. POST /v1/device/challenge — request a one-time challenge (returns challenge_id, challenge_nonce, 5-minute TTL).
  2. The OS produces an attestation over the nonce (Play Integrity token on Android, App Attest object on iOS).
  3. POST /v1/device/register — submit the attestation. The server verifies it and binds the device to your App.
Subsequent SDK requests are signed by the registered device — see Synheart Auth.

​
Troubleshooting

SymptomPlatformWhat to check
Verification fails immediatelyAndroidConfirm the same Cloud project is linked under API access and has the Play Integrity API enabled.
Service account invite not propagatingAndroidRe-open the invited user; verify App permissions lists the correct package(s) and Account permissions has only the read-only report permission.
Wrong app signature after key rotationAndroidPlay App Signing must match what users install from Play; re-check after key rotation.
attestation environment mismatchiOSThe entitlement (production / development) must match the dashboard production toggle on the App.
App Attest not supported at runtimeiOSApp Attest requires iOS 14+ on a real device. Simulator builds cannot attest.
Tokens rejected as too oldBothThe challenge expires after five minutes. Re-fetch a fresh challenge before attesting.

​
Need help?

Contact support@synheart.ai with your Synheart app_id, the platform bundle_id you configured, and the time of the failing attestation. For Android, include screenshots of API access (project name only). For iOS, include the entitlement value from your build.

​
Next

API keys

Issue per-app keys and understand ingestion allowlisting.

Synheart Auth

How registered devices sign every outbound request once attestation has succeeded.