Account Registration & Device Pairing

1. User Account Registration & Login

To use SpotLocker, users register an account either via the mobile application or the web storefront. User credentials are protected using bcrypt password hashing and OAuth2 JWT access tokens.

API Registration Endpoint

When registering an account programmatically or via client interfaces, a POST request is made to /api/v1/auth/register:

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "angler.john@example.com",
  "password": "SecurePassword123!",
  "first_name": "John",
  "last_name": "Doe"
}
        

API Login Endpoint

Authenticating generates short-lived access tokens and refresh tokens:

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=angler.john@example.com&password=SecurePassword123!
        

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "d7a8b9f0e1c2...",
  "token_type": "bearer"
}
        

2. Hardware Device Registration & Pairing

SpotLocker protects waypoint intelligence by binding access licenses to specific registered hardware devices. Every mobile device (iPhone, Android Phone, iPad, Android Tablet) extracts a unique hardware UUID fingerprint upon installation.

⚠️ Device Restriction Policy

Each user account is granted a maximum of 2 active registered devices simultaneously (e.g., 1 Primary Smartphone and 1 Boat Marine Tablet). Attempting to pair a 3rd device without de-registering an older device will trigger a 400 Bad Request and write a too_many_devices audit log entry.

Device Registration Flow

1

App Launch & Fingerprint Detection

The client app queries hardware identifiers (Android ID / iOS Vendor Identifier) via device_service.dart.

2

Device Registration API Call

The app sends a registration request to POST /api/v1/devices/register:

POST /api/v1/devices/register
Authorization: Bearer 
Content-Type: application/json

{
  "device_name": "John's iPhone 15 Pro",
  "device_type": "iOS",
  "device_fingerprint": "a8f9c1d2-3e4b-5c6d-7e8f-9a0b1c2d3e4f"
}
              

3

Server Verification & Device Token Issuance

The server validates active device counts and records the device record in the database. Subsequent requests for licensed waypoint coordinates must include the header X-Device-Fingerprint matching an active paired device.

3. Managing & Deactivating Paired Devices

Users can view and deactivate registered devices from the Account Settings Screen in the mobile app or via the web portal.

💡 Deactivating an Old Device

If you upgrade your phone or replace a boat tablet, navigate to Account > Registered Devices, locate the old device, and tap Deactivate Device. This immediately frees up a slot for your new hardware.