Sign in on iOS and Android

You need: auth composed, and the link your app signs in through decided: an https universal link (iOS) or app link (Android), a custom scheme, or both.

Mobile uses bearer, and it is CSRF-exempt — there is no ambient credential a hostile page could cause the app to send.

Two credentials, and only one goes on every request

The token model is what each one is. Native iOS and native Android are the platform specifics, and sessions and devices is what registering the device buys.

The session token is the credential, and it goes on every request as Authorization: Bearer <session token>. It lives in secure device storage — the Keychain on iOS, the Keystore on Android — and nowhere else. The Worker resolves it on each request, so revoking it takes effect on the next one.

The JWT is not for your app. /auth/token and /auth/token/rotate also hand back a short-lived JWT access token. The kit’s own routes do not accept it. It is for a service outside your Worker that verifies it against /auth/jwks.

pithy ui add react-native scaffolds all of this through createBearerSession from @pithy-sh/auth/src/client/bearer, with expo-secure-store as the store. The rest of this page is what it does, for a client you write yourself.

The flow

1. Ask for a one-time code, and sign in with it.

POST /auth/email-otp/send-verification-otp
{ "email": "…", "type": "sign-in" }

POST /auth/sign-in/email-otp
{ "email": "…", "otp": "123456" }

A magic link on a phone needs a universal link. Whoever asks for a magic link chooses where it returns, and somebody else opens it, so an app that claims your custom scheme could catch the session meant for your user. The Worker hands a magic link off only to an https link in your trusted origins, through the same one-time code as social sign-in; one to a custom scheme gets ?error=handoff_scheme_refused. Every link the app returns on goes in your trusted origins:

auth({
  trustedOrigins: ["myapp://", "https://app.example.com"],
}),

A one-time code is often the better mobile experience: no app-switch to a mail client and back, no deep-link handling to get right, and it works when the mail app opens links in its own browser. The scaffolded React Native sign-in leans on it: with universalLinkOrigin unset, a phone is offered the emailed code and no magic link.

2. Take the token from the answer’s body. A sign-in answers { "token": "…", "user": { … } }, and token is the raw session token — not a cookie, and not the signed set-auth-token header, which the Worker cannot match against a spent credential. Store it in secure storage before you use it.

3. Send it on everything.

GET /auth/get-session
Authorization: Bearer <session token>

Send no cookie beside it. A native fetch may keep one from a sign-in answer, and Better Auth refuses a cookie-carrying request with no Origin. Reading the session also tells you when it expires, which is what the next section needs.

Refresh, and where clients get it wrong

Rotate the session before it expires. POST /auth/token/rotate, with the current token as the bearer, spends it and answers with its successor as refreshToken, and the successor’s expiresAt. Hold the successor from then on. When the session has expired, sign in again.

Two mistakes are common and both are avoidable.

Rotating on a 401. By then the session is gone, and an expired token trades for nothing. Rotate ahead of expiresAt instead. The scaffolded session rotates ten minutes early, which absorbs a phone’s clock running a few minutes off the Worker’s.

Rotating concurrently. The route spends the token it is shown. A second rotation of the same token is refused, and one more than thirty seconds late is read as theft: every session descended from that sign-in is revoked. Single-flight it: one rotation at a time, every request waits for it, and none goes out until the successor is in secure storage.

Registering the device

Optional, opt-in per request, and worth doing.

Send device metadata headers at sign-in and the device is registered and the session is bound to it. There are seven, and only the first is required: x-pithy-device-id, a client-generated stable id of at most 128 characters; x-pithy-platform, ios or android; x-pithy-device-name, a human label; x-pithy-device-model; x-pithy-os-version; x-pithy-app-version; and x-pithy-push-token, if you have one. createBearerSession sends the id, the platform, the name and the model.

Two things follow: a route that lists somebody’s devices, and a route that revokes one. Sign me out on that lost phone becomes a single call rather than a session-invalidation scheme you design yourself.

The stable id is what makes the same physical device map to one row across re-logins. Generate it once and keep it.

Social sign-in on mobile

You do not register a deep link with the provider. They only ever redirect to your Worker’s callback — and the Worker, not the provider, is what hands control back to your app.

The Worker hands the session back with a one-time code, not a cookie. A cookie set on that last redirect would land in the system browser, which the app never reads. So the app proves it started the sign-in, PKCE-style:

  1. Make a verifier with createHandoffVerifier from @pithy-sh/auth/src/client/handoff, and keep it in memory.
  2. Open GET /auth/sign-in/social/start in the system browser’s sign-in sheet (WebBrowser.openAuthSessionAsync), with provider and a callbackURL that is your link carrying the verifier’s S256 challenge as handoff_challenge. nativeSignInStartURL and handoffCallbackURL build both.
  3. The sign-in returns to your link with ?code=…. handoffCode reads it.
  4. Within sixty seconds, POST /auth/handoff with { "code", "verifier" }. The answer is { "token", "expiresAt" }: store token as above.

Never post /auth/sign-in/social from the app for a redirect. Better Auth checks a signed state cookie at the provider’s callback, and only the sheet’s own jar can carry it there. The start route also refuses a navigation another page started, so open it from the app, never from a link.

The code is good once. A spent, expired or unknown code, or a wrong verifier, gets auth/handoff_invalid, and the remedy is to sign in again. Another app that catches your link has the code and not the verifier, so it has nothing to trade. A custom-scheme link with no challenge gets ?error=handoff_challenge_required and no code.

Prefer an https link. The system opens a universal link or app link only in the app that proves it owns the domain; any installed app can claim a custom scheme. An in-app auth session closes on an https callback only on iOS 17.4 or later, so to support an older iOS, return on the scheme.

Apple and Google can sign in natively, and that is simpler. On iOS the app gets an identity token from Apple’s own SDK. On a phone, Google’s SDK gets an id token whose audience is your web client id, the one the Worker checks. Either token is posted to POST /auth/sign-in/social, which answers with the session token. No return URL is involved, which is also why these are the social flows that work from a preview deployment. Apple on Android, Google with no web client id configured, and every other provider take the redirect above.

Add Apple sign-in and Add Google sign-in have the platform-native client id details.

Buying on the phone, entitled everywhere

This is the payoff for putting identity on the server rather than on the device.

A person signs in on iOS, buys through StoreKit, and the purchase resolves to an entitlement row against their user — so the same person on the web is entitled, with nothing synced and no device involved.

Entitlements on mobile and web works it through.

What to check

  • The session token comes back in the sign-in answer’s body and lands in secure storage
  • A protected route accepts it as Authorization: Bearer, with no cookie beside it
  • The session rotates once, ahead of its expiry, and the successor is stored before the next request
  • A revoked device’s session stops working immediately
  • Nothing but secure storage holds the session token
ESC