Comps.gg Documentation

Appearance

Mobile App Onboarding ​

Manage mobile app access and device connections for admin users.

Mobile App QR Code

Route ​

/admin/mobile-app

Overview ​

The Mobile App Onboarding feature allows admin users to securely connect to the mobile app using QR code authentication. This provides a seamless way to access admin features on mobile devices.

How It Works ​

The mobile app onboarding uses a secure token exchange flow:

  1. Admin generates a QR code in the web interface
  2. Mobile app scans the QR code
  3. QR code contains a one-time token
  4. Mobile app exchanges the token for a JWT
  5. Admin is authenticated on the mobile device

Generating a QR Code ​

Steps ​

  1. Navigate to /admin/mobile-app
  2. Click "Generate QR Code"
  3. A unique QR code is displayed
  4. QR code is valid for 5 minutes
  5. Scan with the mobile app to authenticate

QR Code Contents ​

The QR code includes:

  • One-time authentication token (expires in 5 minutes)
  • API base URL
  • Site logo URL (for app branding)
  • Site name

Managing Connected Devices ​

Connected Devices

Viewing Devices ​

The Mobile App page displays all connected devices:

  • Device Name - Name of the mobile device
  • Platform - iOS or Android
  • Last Active - Last time the device was used
  • Connected On - When the device was first connected

Revoking Device Access ​

To remove a device:

  1. Find the device in the connected devices list
  2. Click "Revoke Access"
  3. Confirm the action
  4. Device will need to re-authenticate with a new QR code

Security Features ​

Token Expiration ​

  • One-time tokens expire after 5 minutes
  • Each token can only be used once
  • Old tokens are automatically cleaned up

Automatic Cleanup ​

A scheduled job runs periodically to remove:

  • Expired onboarding tokens
  • Old device sessions

Device Tracking ​

All device connections are tracked with:

  • Device identifier
  • Platform information
  • Last activity timestamp
  • IP address (optional)

API Endpoints ​

Admin Endpoints ​

  • POST /api/v1/admin/app/generate-qr - Generate QR code
  • GET /api/v1/admin/app/devices - List connected devices
  • DELETE /api/v1/admin/app/devices/:deviceId - Revoke device

Public Endpoint ​

  • POST /api/v1/admin/app/exchange-token - Exchange one-time token for JWT (used by mobile app)

Use Cases ​

First-Time Setup ​

  1. Admin opens web admin panel
  2. Navigates to Mobile App section
  3. Generates QR code
  4. Opens mobile app
  5. Scans QR code
  6. Mobile app is now authenticated

Multiple Devices ​

Admins can connect multiple devices:

  • Work phone
  • Personal phone
  • Tablet

Each device appears in the connected devices list and can be revoked independently.

Security Audit ​

Review connected devices regularly:

  • Check for unfamiliar devices
  • Remove old or unused devices
  • Monitor last active times

Troubleshooting ​

QR Code Won't Scan ​

  • Ensure QR code hasn't expired (5 minute limit)
  • Check camera permissions on mobile device
  • Ensure good lighting for QR code scanning
  • Try generating a new QR code

Token Exchange Failed ​

  • Token may have expired
  • Token may have already been used
  • Generate a new QR code and try again

Device Not Showing in List ​

  • Device may have failed to complete authentication
  • Try the onboarding process again
  • Check mobile app logs for errors

Best Practices ​

  1. Regular Review - Periodically review connected devices
  2. Revoke Unused Devices - Remove devices no longer in use
  3. Secure QR Display - Don't share QR codes with others
  4. Token Expiration - Be aware tokens expire after 5 minutes
  5. Device Naming - Use clear device names for easy identification

Technical Details ​

Token Lifecycle ​

1. Admin requests QR code
   → Server generates one-time token (UUID)
   → Token stored in database with 5-minute expiration

2. Mobile app scans QR code
   → Extracts token and API URL

3. Mobile app exchanges token
   → POST /api/v1/admin/app/exchange-token
   → Token validated and marked as used
   → JWT returned for subsequent API calls

4. Background cleanup
   → Expired tokens removed every hour

Security Considerations ​

  • Tokens are single-use only
  • Tokens expire after 5 minutes
  • JWTs follow standard authentication flow
  • Device revocation is immediate
  • All device connections are logged