Mobile app integration

Guidance for iOS, Android, React Native, and Flutter apps consuming the botso.ai member and operator 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	`POST /v1/botso/pools/{slug}/checkout/revolut` (Passport) — or shop `POST /v1/shop/checkout`
Commit capital (desk)	`POST /v1/botso/pools/{slug}/checkout/revolut/capital`
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
Create private syndicate	`GET /v1/botso/syndicate-availability` then `POST /v1/botso/organizations` (any member; gate on `can_create`)
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.