Session Tokens & Heartbeats

30-day Bearer tokens, periodic validation, and automatic logout on expiry.

Overview

After successful license verification, the desktop client must obtain a session token via POST /api/auth/login. This token is used as a Bearer header for all subsequent heartbeat requests to POST /api/auth/heartbeat.

Login Flow

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "...",
  "machineId": "sha256-hash",
  "machineName": "DESKTOP-ABC123",
  "appVersion": "1.2.3"
}

Response (200):

{
  "sessionToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2025-01-15T10:30:00Z",
  "license": {
    "plan": "Pro",
    "maxMachines": 3,
    "expiresAt": "2025-12-01T00:00:00Z"
  }
}

Error responses:

  • 401 - Invalid credentials
  • 402 - License expired or payment required
  • 429 - Rate limited (max 5 attempts/min)

Heartbeat

Send periodic heartbeats every 5 minutes to keep the session alive and update LastSeenAt on the server:

POST /api/auth/heartbeat
Authorization: Bearer {sessionToken}
Content-Type: application/json

{
  "machineId": "sha256-hash",
  "appVersion": "1.2.3",
  "ipAddress": "auto"
}

Response (200):

{
  "valid": true,
  "license": { "plan": "Pro", "maxMachines": 3 },
  "serverTime": "2025-01-15T10:30:00Z"
}

If valid: false, the client must immediately lock Pro features and prompt for re-login.

Logout

On explicit sign-out or app exit, call:

POST /api/auth/logout
Authorization: Bearer {sessionToken}

This invalidates the session token server-side. The client must also clear all stored credentials.