> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Mobile API

How the app talks to the server — sessions, reachability, and payloads.

## Beginner walkthrough

Prerequisites: Read the two beginner guides below and finish Mobile local setup. Put Expo values in `apps/mobile/.env.local`; set `EXPO_PUBLIC_API_URL` to a backend host your device can reach. A mobile-only checkout has no web backend, so start or connect one separately. A successful Expo export proves the JavaScript bundle, not device or purchase acceptance.

Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.

1. In `apps/mobile/.env.local`, set `EXPO_PUBLIC_API_URL` to the running backend address reachable from your phone; do not use `localhost` from a physical device.

2. Follow Mobile local setup to start Expo, sign in, and open workspace, settings, and chat screens.

3. Expect authenticated data from the same workspace. If requests time out, check the phone and computer network and start the backend separately in a mobile-only checkout.

For custom code, start with the supplied `prompts/README.md` and copy the closest prompt: `prompts/new-app-screen.md` for an app screen or `prompts/new-landing-page.md` for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read `AGENTS.md`, `.ai/PROJECT_CONTEXT.md`, and matching `.ai/` mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.

[Before you start](https://supastack.dev/docs/web/before-you-start.md)

[Terminal basics](https://supastack.dev/docs/web/terminal-basics.md)

[Mobile local setup](https://supastack.dev/docs/mobile/ship-in-5-minutes.md)

[Agent prompts & project memory](https://supastack.dev/docs/web/agents.md)


## Understand native scope

Expo includes native auth/session and deep links alongside workspace, settings, chat, and RevenueCat purchase surfaces. Shared business behavior and authorization stay in the web backend/packages; native clients under `apps/mobile/src` call those APIs without embedding provider credentials.


## Use the session-authenticated BFF

The `/api/mobile` routes cover entitlement, RevenueCat purchase availability and server sync, organization, members, invitations, audit, API keys, webhooks, domains, schedules and feature requests. They preserve workspace ownership and role checks. They are different from the `sk_` bearer-key `/api/v1` public contract.

Use your device-reachable `EXPO_PUBLIC_API_URL` and the configured origin/scheme; public Expo variables never contain provider credentials.


## Verify on native targets

Check loading/error/empty states, reconnect, expired session, forbidden management actions and deep-link returns on the device/build you intend to support. An Expo export proves bundling, not native delivery or purchase acceptance.

[All API routes](https://supastack.dev/docs/web/project-structure.md)

[Native session flow](https://supastack.dev/docs/mobile/authentication.md)


## Setup and configuration

The app calls the API under /api/mobile and the versioned /api/v1 surface with the member's session rather than cookie assumptions from the web app. EXPO_PUBLIC_API_URL is the only origin the client knows; it is public by design and carries no secrets.

Session tokens come from the Better Auth Expo flow and are kept in native secure storage — never in plain AsyncStorage or bundled config.

```
GET  /api/mobile/entitlement    # access state for the member
GET  /api/mobile/organization   # active workspace context
GET  /api/mobile/usage          # current-month AI spend, meter caps, and credit balance
GET  /api/mobile/appearance     # synced appearance bundle (GET/PUT)
POST /api/v1/ai-tasks            # authorized work, same as web

Session: /api/auth/* (Better Auth Expo flow)
# Optional server-only token for authenticated Expo push sends:
# EXPO_ACCESS_TOKEN=
```


## Implementation workflow

Resolve the stored session before the first authenticated request, refresh it when the server reports expiry, and sign out cleanly when it is revoked. Treat unreachable API and invalid session as different states — one retries, the other returns to sign-in.

Keep payloads identical to the web contract: the server applies the same workspace, entitlement, and validation rules regardless of which client called.


## Verification and troubleshooting

Test airplane-mode failures, expired tokens mid-session, revoked sessions, and a cold start with a stored valid token. A request that fails closed (denied) is correct; one that fails open is a bug to fix before release.


## Next

[Native UI and theming](https://supastack.dev/docs/mobile/ui.md)