Sign in
Signing in on mobile is the flow, choosing a client credential is why it ends in a bearer token, selling on Google Play is the purchase half, and gaps in Play APIs is what Google does not expose.
Passwordless. A magic link or an emailed one-time code — six digits, five minutes, single-use.
Google Sign-In is available as a social provider. Enable it, then store the client id and secret as one atomic secret — both halves travel together so the pair is never split across config and store.
A magic link back to the app needs an https app link, and its origin in auth’s trustedOrigins. The Worker refuses to hand a magic link to a custom scheme, because any installed app can claim one; without an app link, use the emailed code. A redirect provider returns to your link with a one-time code, and the app trades it for the session token at POST /auth/handoff. Social sign-in on mobile has the steps.
Hold one credential
The session token a sign-in answers with, in the Keystore, on every request as Authorization: Bearer, and rotated at POST /auth/token/rotate for a successor. Rotation also answers with an accessToken JWT. Do not send it to your Worker: the kit’s routes do not accept it. It is for a service outside the Worker that verifies against /auth/jwks.
Rotate before the session expires, not on a 401. GET /auth/get-session tells you when it expires, and so does each rotation’s expiresAt; rotate about ten minutes ahead, and store the successor before the next request. A 401 means the session is gone: sign in again, because an expired or revoked token trades for nothing. A 403 means you are not allowed, and rotating will not change that. A client that treats the two the same refreshes a perfectly good token forever.
A replay inside 30 seconds is denied and nothing else. Past that, the whole family is revoked — so do not fire two rotations concurrently from two coroutines.
Register the device
x-pithy-device-id, at most 128 characters, is the only required header. The other six are best-effort: x-pithy-platform: android, x-pithy-device-name, x-pithy-device-model, x-pithy-os-version, x-pithy-app-version and x-pithy-push-token.
Keep the id stable across launches.
Buying things
Submit the receipt to your Worker as soon as the purchase completes, and gate on the entitlement key rather than the Play product id.
One entitlement, many products, five rails — that indirection is what lets somebody buy on Play and be entitled on the web.
The Play requirement, and the capability for it
A personal developer account created after 13 November 2023 must run a closed test with 12 testers opted in for 14 continuous days.
The days must be consecutive — lose one tester on day nine and the clock effectively restarts.
Adding an address to a Play email list is a manual step in the Console, because the API cannot do it — which is why the tester journey is two emails rather than one.
Translate errors on the client
t.maybe(payload.code, payload.params) ?? payload.messageThe code is the translation key, and the English always arrives on the wire as the fallback.
Uploading
Presigned URL, PUT to R2, then complete. Multipart above 100 MiB, resumable by re-listing parts.