Mobile App¶

Access TradeTally from your iOS device with native mobile app support.

Overview¶

TradeTally includes a companion iOS mobile app that connects to your TradeTally instance through the REST API v1. The mobile app provides access to your trades, analytics, and alerts on the go, with native push notifications and device management.

The mobile API is available at /api/v1/ and includes dedicated endpoints for device registration, authentication with refresh tokens, push notification management, and data synchronization.

Getting Started¶

iOS TestFlight¶

The TradeTally iOS app is available through Apple TestFlight for beta testing. Visit the TradeTally mobile app repository for TestFlight access links and installation instructions.

Connecting to Your Instance¶

1. Open the TradeTally app on your iOS device.
2. Enter your TradeTally server URL (e.g., https://tradetally.example.com).
3. Sign in with your email and password.
4. The app automatically registers your device and establishes a secure session.

Authentication¶

Login with Device Registration¶

The mobile app uses an enhanced login flow that registers the device during authentication:

1. The app sends credentials along with device information (device name, model, OS version, fingerprint).
2. The server authenticates the user and registers or updates the device record.
3. Both an access token and a refresh token are returned.

JWT Refresh Token Flow¶

Mobile sessions use a refresh token system for seamless authentication:

1. Access token -- Short-lived JWT used for API requests. Sent as Authorization: Bearer <token>.
2. Refresh token -- Long-lived token used to obtain new access tokens without re-entering credentials.
3. When the access token expires, the app sends the refresh token to POST /api/v1/auth/refresh.
4. A new access token and rotated refresh token are returned.

POST /api/v1/auth/refresh
{
  "refreshToken": "<refresh_token>"
}

Session Management¶

The v1 API provides several session management endpoints:

Device Management¶

Registering a Device¶

Devices are registered automatically during the login flow or can be registered manually:

POST /api/v1/devices
{
  "name": "iPhone 15 Pro",
  "deviceType": "ios",
  "model": "iPhone15,3",
  "osVersion": "18.0",
  "appVersion": "1.0.0",
  "fingerprint": "unique-device-fingerprint"
}

Device Limits¶

Each user can register up to a configurable number of devices (default: 10). This limit is controlled by the MAX_DEVICES_PER_USER environment variable.

When the device limit is reached, you must remove an existing device before registering a new one.

Trusted Devices¶

Devices can be marked as trusted or untrusted for security purposes:

• Trust a device -- POST /api/v1/devices/:id/trust
• Untrust a device -- POST /api/v1/devices/:id/untrust

Trusted devices may receive enhanced session durations or reduced re-authentication requirements.

Device Endpoints¶

Push Notifications¶

Enabling Push Notifications¶

Push notifications require server-side configuration with Apple Push Notification Service (APNS) credentials.

Required environment variables:

ENABLE_PUSH_NOTIFICATIONS=true
APNS_KEY_PATH=/path/to/AuthKey_XXXXXXXXXX.p8
APNS_KEY_ID=XXXXXXXXXX
APNS_TEAM_ID=YYYYYYYYYY

Registering a Push Token¶

After the mobile app obtains a device token from iOS, it registers the token with the server:

POST /api/v1/devices/current/push-token
{
  "token": "<apns_device_token>",
  "platform": "ios"
}

Supported Push Notification Types¶

The following events trigger push notifications to registered devices:

Token Lifecycle¶

• Tokens are marked as active when registered.
• If Apple reports a token as invalid (BadDeviceToken or 410 status), the token is automatically marked inactive.
• Users can manually remove push tokens via DELETE /api/v1/devices/current/push-token.

File Uploads¶

The mobile API supports file uploads with a default maximum size of 52 MB. This is used for importing trade CSV files from your mobile device. The upload limit can be adjusted via server configuration.

Available API Endpoints¶

The mobile app has access to the full v1 API, including:

• Trades -- List, create, update, delete, and bulk operations
• Analytics -- Trading performance metrics and summaries
• Settings -- User preferences and configuration
• Devices -- Device management and push tokens
• Server -- Server information and health checks

For complete API endpoint documentation, see the API Keys and Webhooks page or the interactive API docs at /api-docs on your instance.

Billing (iOS In-App Purchase)¶

The mobile app supports Apple In-App Purchase for Pro tier subscriptions. Transactions are verified server-side using StoreKit 2 JWS signed transactions. The server validates the transaction, grants Pro tier access, and stores the transaction record.

For self-hosted instances, billing is typically disabled and all features are available to all users regardless of the app's purchase flow.