Mobile app integration

Guidance for iOS, Android, React Native, and Flutter apps consuming the botso.ai member and club-admin APIs.

Overview

Mobile apps use the same REST API as the web client dashboard. There is no separate mobile SDK — implement a thin API client layer mirroring client_dashboard_v1/src/api/client.js.

App type	Auth flow	Typical permissions
Member app	Password grant	`botso_access` only
Club admin app	Password grant	`botso_access` + org admin membership
White-label partner	Password grant + branded OAuth client	Per partnership

Authentication

Call POST /api/v1/auth/login with email, password, and your public client_id. Store the returned access_token and expires_at.

Tokens expire. On 401, clear stored credentials and show the login screen. Re-login is required — refresh tokens are not issued for the client dashboard grant today.

Recommended login sequence

1. POST /v1/auth/login 2. Persist access_token + expires_at + user JSON 3. If user.organizations.length === 1 → save org slug 4. If length > 1 → show club picker → save selected slug 5. GET /v1/botso/pools (home screen data)

Secure token storage

Platform	Recommendation
iOS	Keychain via `expo-secure-store` or native Keychain APIs
Android	EncryptedSharedPreferences or Keystore-backed storage
React Native	`expo-secure-store` — never AsyncStorage for tokens
Flutter	`flutter_secure_storage`

Also persist botso_org (organization slug) alongside the token. Clear both on logout.

Organization switching

Club members often belong to multiple pools across orgs. Expose a club switcher in settings that:

Reads GET /v1/auth/me or cached user.organizations.
Updates stored org slug.
Refetches pool list and invalidates cached pool detail screens.

Send header on every org-scoped request:

Headers

Authorization: Bearer {access_token}
X-Botso-Organization: {org_slug}
Accept: application/json

Member app screens → API mapping

Screen	Endpoints
My pools	`GET /v1/botso/pools`
Pool dashboard	`GET /v1/botso/pools/{slug}/overview`
Daily PnL chart	`GET /v1/botso/pools/{slug}/daily-pnl?month=YYYY-MM`
Buy a ticket	Payment processor API (coming soon) — same login token
Payout history	`GET /v1/botso/pools/{slug}/payouts`
My earnings	`GET /v1/botso/pools/{slug}/earnings`
Profile	`GET /v1/auth/me`, `PUT /v1/auth/profile`
Verify WhatsApp	`POST /v1/auth/profile/verify-whatsapp`

Club admin screens → API mapping

Requires org admin or owner role (or platform botso_manage).

Screen	Endpoints
Assign ticket	`POST /v1/botso/pools/{slug}/tickets`
Record payment	`POST /v1/botso/pools/{slug}/payments`
Fund pool	`POST /v1/botso/pools/{slug}/fund`
Members list	`GET /v1/botso/pools/{slug}/members`
Audit log	`GET /v1/botso/audit-log`

Networking patterns

Central API client

Wrap fetch / URLSession / OkHttp with:

Base URL config per build flavor (dev/staging/prod).
Automatic Authorization and X-Botso-Organization injection.
JSON parse with unified error type (message from Laravel).
401 handler → logout navigation.

Offline & caching

Pool overview and payout history are good candidates for short TTL cache (30–60s). Ticket assignment and payments must be online-only with optimistic UI disabled.

Deep links

Support botso://pool/{slug} or universal links to open a pool detail screen after auth.

Push notifications & WhatsApp

Club-level SMS/WhatsApp alerts are configured via org admin endpoints (/v1/botso/organization/twilio, .../whatsapp). Mobile apps should:

Encourage members to verify phone via POST /v1/auth/profile/verify-whatsapp.
Use native push (FCM/APNs) for your own app events — botso.ai does not yet expose a push registration API; coordinate with platform team for webhook events.