A web page proves a human is there with Turnstile. A native app has no widget to solve. It can prove something else instead: that the request came from your app, unmodified, on a real device. Apple calls that App Attest. Google calls it Play Integrity. Auth’s send routes take an attestation in place of a Turnstile token, and this page is how that works.
What it gates
The two routes that send a sign-in email: POST /auth/sign-in/magic-link and POST /auth/email-otp/send-verification-otp. Signing up goes through the same two routes, so it is gated too. Nothing else.
The rule: either passes
- A request carrying an attestation is judged by attestation, and only by attestation. If it fails, the request is refused. It never falls through to Turnstile.
- A request without one goes to Turnstile when turnstile is composed, exactly as before.
- Without turnstile composed, a request with no attestation is refused with
auth/attestation_missingin an environment that has an attestation block, and passes in one that has none.
So one Worker can serve your web page through Turnstile and your app through attestation, with turnstile composed or not.
Configuring it
The block lives on auth(), per environment, keyed by the name the Worker is stamped with:
auth({
baseURL: "https://api.example.com",
attestation: {
environments: {
dev: { mode: "test" },
staging: { mode: "test", ios: [{ teamId: "ABCDE12345", bundleId: "com.example.app" }] },
prod: {
mode: "enforce",
ios: [{ teamId: "ABCDE12345", bundleId: "com.example.app" }],
android: [{ packageName: "com.example.app" }],
},
},
},
});| Key | Meaning |
|---|---|
environments.<env>.mode | enforce, the default, or test |
environments.<env>.ios | The iOS apps allowed to attest: the Apple Team ID, ten uppercase letters or digits, and the bundle identifier |
environments.<env>.android | The Android apps allowed to attest: the package name |
challengeExpiresIn | How long a challenge stays usable, in seconds. 300 by default, 600 at most |
An enforce block must allow at least one app, or no attestation could ever pass it, so auth’s config refuses one that allows none. A real assertion from a platform with no app listed is refused. The test assertion is judged by the mode and the environment alone. An environment with no block keeps its send routes exactly as they were.
A project that never configures attestation gets nothing new. No new route is mounted and no new dependency is installed. pithy migrate creates two new tables, pithy_auth_attestation_challenges and pithy_auth_app_attest_keys, and nothing writes to either. Verification runs on WebCrypto, with auth’s own CBOR and certificate reader for App Attest and its own JWT signer for Play Integrity, and @pithy-sh/auth takes no dependency for either.
The flow
- Ask for a challenge.
POST /auth/attestation/challengeis public and answers{ challenge, expiresAt }. The challenge is 32 random bytes as unpadded base64url, good once, untilexpiresAt. Auth stores only its SHA-256. An environment with no block answersauth/attestation_config. - Attest over the request. Hash the challenge’s characters followed by the send’s exact body bytes with SHA-256. That digest is App Attest’s
clientDataHash, and its unpadded base64url is Play Integrity’srequestHash. It binds the attestation to this challenge and this body, so it cannot be lifted onto another address. - Send it in one header.
x-pithy-attestationcarries unpadded base64url over the JSON{ "platform": "ios" | "android", "challenge": "…", "assertion": "…", "keyId": "…" }, at most 16,384 characters.assertionis the App Attest assertion fromgenerateAssertion, or the Play Integrity token, as the platform hands it over. On iOS the key must already be registered: the attestation object fromattestKeygoes once toPOST /auth/attestation/ios/keys, never in this header.keyIdis App Attest’s key identifier; Android has none.
Why a header and not the body? The send routes’ bodies belong to Better Auth and are forwarded untouched. The attestation signs over those exact bytes, so it cannot sit inside them.
The challenge is spent the moment it is presented, pass or fail. A failed attempt asks for a new one.
Apple App Attest
What goes in config
Each iOS app is one entry in ios: { teamId, bundleId }. Together they are the app’s App ID, <teamId>.<bundleId>, and App Attest signs over its SHA-256.
teamIdis your Apple Developer Team ID: ten uppercase letters and digits, such asABCDE12345. Find it at developer.apple.com/account under Membership details, or in Xcode on the target’s Signing & Capabilities tab. If the app’s identifier in Certificates, Identifiers & Profiles shows an App ID prefix other than the Team ID, which only very old apps have, use that prefix.bundleIdis the app’s bundle identifier, such ascom.example.app. Find it in Xcode on the target’s General tab under Identity, or in an Expo app’sapp.jsonasios.bundleIdentifier.
List every app that may attest in that environment. A staging build with its own bundle identifier is its own entry in the staging block.
The app needs the App Attest capability in Xcode, which adds the com.apple.developer.devicecheck.appattest-environment entitlement. Its value picks Apple’s environment, and auth reads it from the attestation: a production key is accepted everywhere, and a development key only where the Worker’s ENVIRONMENT is dev, staging or feature, the same rule test mode follows. A development key in prod is refused. TestFlight and App Store builds attest in production.
Registering a key
Once per key, before its first assertion:
- The app calls
generateKey()and keeps the key id. - It asks
POST /auth/attestation/challengefor a challenge. - It calls
attestKey(keyId, clientDataHash:)with SHA-256 of the challenge’s characters: the binding over the challenge and an empty body. - It sends
POST /auth/attestation/ios/keyswith{ "challenge": "…", "keyId": "…", "attestation": "…" }, the key id and the attestation object base64 as Apple hands them over. A key that registers answers{ keyId, registeredAt }.
Auth spends the challenge, then checks the attestation Apple’s way: the certificate chain leads to Apple App Attestation Root CA, which ships pinned in the package, and is valid now; the certificate’s nonce is bound to this challenge; the certificate’s key hashes to the key id; the rpIdHash is SHA-256 of an allowed app’s App ID; the counter is zero; the AAGUID names an environment accepted here; and the credential id is the key id. It stores the key id, the public key, the App ID, the environment and a counter of zero in pithy_auth_app_attest_keys. A key registers once: registering it again is refused, so its counter cannot be reset. A key belongs to one install of the app and names no person.
The route is public, and mounted only when some environment has a block, beside the challenge route. An environment with no block answers auth/attestation_config there too.
Each send
The app calls generateAssertion(keyId, clientDataHash:) with the binding over a fresh challenge and the send’s exact body, and sends the assertion as assertion with the key id as keyId in x-pithy-attestation. Auth finds the key, checks that its app is still allowed and that a development key is accepted here, checks the rpIdHash, verifies the signature over the binding with the stored public key, and requires the counter to rise above the stored one. Then it stores the new counter, so a replayed assertion is refused.
Refusals
Every App Attest check that fails is auth/attestation_failed, and detail starts with the check that failed: challenge, format, chain, nonce, keyId, key (no key with that id is registered), rpIdHash, aaguid, credentialId, signature or counter. A send with no keyId fails on keyId. The gate’s own refusals come first, worded as the three refusals say: a header that does not decode, or a send from a platform with no allowed app.
Google Play Integrity
What goes in config
Each Android app is one entry in android: { packageName }, the application id Google Play knows it by, such as com.example.app. Find it in build.gradle as applicationId, or in an Expo app’s app.json as android.package. List every app that may attest in that environment.
The service account
The Worker decodes each token through Google’s decodeIntegrityToken, signed in as a Google Cloud service account. One service account serves every app in an environment.
- Create it. In Google Cloud Console, pick the project the app uses for Play Integrity, or create one, and enable the Google Play Integrity API under APIs & Services. Under IAM & Admin > Service accounts, create a service account. It needs no role.
- Make a key. On the service account, open Keys, choose Add key > Create new key, pick JSON, and save the file. It is the only copy.
- Link the project in Play Console. In Play Console, open the app, then Test and release > App integrity > Play Integrity API, and link the same Google Cloud project. The app requests tokens for that project’s number, and only that project’s service accounts can decode them.
- Store it. Paste the whole JSON file as the
auth-play-integrity-service-accountsecret, once per environment.
pithy secrets create auth-play-integrity-service-account --env prod < service-account.jsonThe key’s private_key spans many lines, so pithy secrets asks for the file as one JSON document rather than field by field. Auth keeps client_email, private_key, private_key_id, project_id, client_id, token_uri and type, and drops the rest. pithy secrets ls lists the secret, and pithy doctor reports it missing, once any environment lists an Android app. Delete the downloaded file once it is stored.
To rotate, add a new key to the service account, store it with pithy secrets update, then delete the old key in Cloud Console.
Each send
The app asks Play Integrity for a standard-request token whose requestHash is the unpadded base64url of the binding, and sends the token as assertion in x-pithy-attestation, with no keyId. The Worker signs an RS256 assertion with the service account’s key, exchanges it at Google’s token endpoint for an access token, which it reuses until a minute before it expires, and calls decodeIntegrityToken for each allowed package until one decodes. Then it requires, in order:
requestHashinrequestDetailsto be the binding over this challenge and this body. A classic request’snonceis checked the same way when it carries norequestHash.requestPackageNameto be the package Google decoded the token for.appRecognitionVerdictto bePLAY_RECOGNIZED.appIntegrity: itspackageNameto be that same package.requestPackageNameis only what the caller asked for, so this is the check that ties the token to your app rather than to any app Google Play distributes.deviceIntegrityto includeMEETS_DEVICE_INTEGRITY.timestamp:timestampMillisno more than five minutes old, and no more than a minute ahead of the Worker’s clock.
The licensing and account verdicts are not checked. The challenge is single-use, so a replayed token is refused with it.
Refusals
A verdict that fails is auth/attestation_failed, and detail starts with the check: decode (Google would decode the token for no allowed package), requestHash or nonce, requestPackageName, appRecognitionVerdict, appIntegrity, deviceIntegrity, timestamp, or format.
A fault in your setup is auth/attestation_config, and never blames the user: no service account stored, a key that is not an RSA PEM, Google’s token endpoint refusing the account, or decodeIntegrityToken answering 401, 403 or 404, which means the API is not enabled or the project is not linked to the app. Google failing outright, unreachable, a 429 or a 5xx, or an answer with no token or payload in it, is core/upstream_failed (502), and a call that runs past ten seconds is core/upstream_timeout (504).
The client
pithy ui add react-native wires all of this for you, and React Native says what the app sends where. A client of your own built on the kit’s packages uses @pithy-sh/auth/src/client/attestation:
import { sendOtp } from "@pithy-sh/auth/src/client/api";
import { createAttestation, testAttester } from "@pithy-sh/auth/src/client/attestation";
const attestation = createAttestation({ ...session.options, attester: testAttester("ios") });
const sent = await sendOtp({ email, type: "sign-in" }, { ...session.options, attestation });createAttestation asks the challenge route for a challenge before each send, hands the attester the challenge, the exact body and their binding, and puts the result in x-pithy-attestation. With attestation set, the send carries no Turnstile token. The attester is injected:
testAttester(platform)sends the test assertion.appAttestAttester({ module, store })is App Attest.moduleis@expo/app-integrity, andstorekeeps the key id. With no registered key, a send first registers one, and keeps its id only when the route answers that it registered it. Then the send, and every later one, asserts over its own challenge and the exact body. A refused registration is not kept, and the send answers the route’s code with nothing sent. A key refused at a send is dropped, never a newer one another send registered since, and so is one the device can no longer assert with after a reinstall or a restore; a new one is registered.playIntegrityAttester({ module, cloudProjectNumber })is Play Integrity. It prepares the token provider, again after any failure to prepare it or to get a token, and asks for a token whoserequestHashis the binding’s unpadded base64url.
@pithy-sh/auth never depends on @expo/app-integrity. The app installs it and passes it in, so a web-only or server-only project installs nothing for attestation. 0.1.9, an Expo SDK 54 release, is the first with the calls this client makes, and the scaffold pins ~57.0.2.
A refusal keeps its code. A refused send answers an AuthResult whose failure.code is the gate’s, one of the three below or a turnstile/* code, and isGateRefusal(failure) says whether it is, so a screen can show it without telling a registered address from another. A device that would not attest answers client/attestation_unavailable, and nothing was sent.
Test mode
Simulators, emulators and CI cannot produce a real attestation. In an environment set to test, the gate also accepts the test assertion, from either platform:
pithy-test-attestationSend it as assertion, with a real challenge from the challenge route. The challenge is still single-use and still expires.
Production never accepts it. The Worker accepts the test assertion only where its ENVIRONMENT is dev, staging or feature, whatever the config says. Everywhere else it is refused: prod, an unstamped Worker, and every name your project declares, because a deployed Worker cannot read seed.productionEnvironments to tell a declared production name from any other. So test mode in a declared environment does nothing; use staging or a feature environment for simulators and CI.
Two more checks hold the configuration before it ships, for prod and every name in the root config’s seed.productionEnvironments. pithy doctor reports a production environment set to test in its Attestation: block, and pithy deploy refuses to ship one, exit 3.
The three refusals
| Code | Status | When |
|---|---|---|
auth/attestation_missing | 400 | The environment has a block, turnstile is not composed, and the request carried no attestation |
auth/attestation_failed | 403 | The attestation did not verify: a header that does not decode, a challenge that is stale, reused or never issued, a real assertion from a platform with no allowed app, an App Attest key that does not register, an assertion that does not check out, a Play Integrity verdict that fails, or the test assertion where it is not accepted |
auth/attestation_config | 500 | The server cannot judge it: the environment has no attestation block, no verifier for the platform is available, or the Play Integrity service account is missing or refused by Google |
Each one says why in detail, which goes to the operator’s log and never to the client. The client sees the code, the status and a short message. The error codes page lists them beside the rest.