Native iOS

Sign in

Signing in on mobile is the flow and Apple Sign-In the provider; choosing a client credential is why it ends in a bearer token; selling on the App Store is the purchase half.

Passwordless, always. There is no emailAndPassword anywhere in the kit.

Two flows, both through the auth capability’s Better Auth surface: a magic link, or an emailed one-time code — six digits by default, five minutes, single-use regardless.

A code is usually the better fit on a phone, because a magic link opening in the wrong browser is the classic mobile sign-in dead end.

A magic link back to the app needs an https universal 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 a universal link, use the emailed code. A redirect provider — Google, GitHub, Microsoft, Facebook, or Apple through the web flow — 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.

Apple Sign-In is available as a social provider. Enable it, then store the credentials as one atomic secret — the Services id, the client secret, and optionally the app bundle id.

Hold one credential

The session token a sign-in answers with goes on every request as Authorization: Bearer, and you rotate it for a successor before it expires. 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.

Keep the session token in the Keychain, and nowhere else. It is the credential worth protecting.

Rotate, and handle the two failures differently

POST /auth/token/rotate
Authorization: Bearer <session token>

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 of that, which also absorbs a phone clock running a few minutes off the Worker’s. The answer’s refreshToken is the successor. Store it in the Keychain before the next request goes out.

A 401 means the session is gone: sign in again. An expired or revoked token trades for nothing, so there is nothing to retry. And never present a spent token. Rotation spends the token it is shown; showing it again is refused, and after a thirty-second grace it is read as theft, which revokes every session descended from that sign-in. One rotation at a time, and every request waits for it.

A 403 is not a credential problem. It means not allowed, or with auth/account_suspended or auth/account_deleted, an account somebody stopped. Rotating will not fix it. 401 and 403 are the pair worth separating, and treating them the same is the most common client bug against this API.

Register the device

x-pithy-device-id: <a stable id you generate and keep, at most 128 characters>
x-pithy-platform: ios
x-pithy-device-name: …
x-pithy-device-model: …
x-pithy-os-version: …
x-pithy-app-version: …
x-pithy-push-token: …

Only the id is required. The rest is best-effort, and a sparse re-login never overwrites richer detail you sent before.

Generate the id once and keep it stable. A value that changes per launch turns the user’s device list into something nobody can read.

Buying things

Submit the receipt to your own Worker the moment a purchase completes:

POST /payments/purchases

The entitlement appears immediately rather than waiting for Apple’s webhook — and when the webhook lands it finds the row already there, because the write path is idempotent on (rail, providerTransactionId).

A replay by its own owner is a 200 with the existing purchase. A receipt belonging to somebody else is not.

Gate on the entitlement key, never the SKU:

GET /payments/entitlements

Translate errors on the client

t.maybe(payload.code, payload.params) ?? payload.message

The server’s message is English, permanently — it is the operator’s diagnostic and the fallback for a client that cannot do better.

The code is the translation key, and params is what lets you build the sentence in any language.

Better Auth’s own refusals are the exception and arrive already translated server-side, in the locale this project negotiated — so a mistyped one-time code reads in the user’s language without your app shipping a catalog for it.

Uploading

Ask your Worker for a presigned URL, PUT the bytes straight to R2, then complete. The bytes never pass through your Worker.

Above 100 MiB it goes multipart, and a dropped upload resumes by re-listing parts rather than starting over.

ESC