Specification: Aether V3 API Device Config Payload

Endpoint: GET /v3/crud/event_device/{id_random}?view=native_bootstrap Goal: Provide full operational context to an Electron instance with zero local configuration.

1. Response Structure (Draft)

{
  "status": "success",
  "data": {
    "identity": {
      "device_id_random": "GZvFjgIIZQg",
      "device_code": "macbook_air_scott_idem",
      "account_id_random": "xFP7AhU8Zlc",
      "event_id_random": "UFu-gF-rZ-ws",
      "location_id_random": "PFGP-37-81-80"
    },
    "network": {
      "api_base_url": "https://api.oneskyit.com",
      "file_server_url": "https://files.oneskyit.com",
      "heartbeat_interval_ms": 30000
    },
    "filesystem": {
      "cache_path": "[home]/Library/Caches/OSIT/file_cache",
      "temp_path": "[home]/tmp/OSIT/temp",
      "use_sharding": true,
      "verify_on_launch": true
    },
    "launcher": {
      "app_mode": "native",
      "auto_start_slideshow": true,
      "prevent_sleep": true,
      "whitelisted_apps": ["PowerPoint", "Keynote", "Acrobat Reader"]
    },
    "ui_prefs": {
      "theme_name": "cerberus",
      "theme_mode": "dark",
      "show_clock": true,
      "show_admin_tools": false
    }
  }
}

2. Key Payload Fields

2.1 Identity & Scoping

account_id_random: Automatically scopes all subsequent V3 API calls for the SvelteKit UI.
location_id_random: Locks the UI to a specific room/podium.

2.2 Filesystem Strategy

cache_path: Uses the [home] placeholder. The Electron Main process will resolve this to the local user profile.
use_sharding: Tells the Sync Engine to use the /ab/abcdef... directory structure.

2.3 Automation Whitelist

To prevent security risks, the launcher object defines exactly which applications the native shell is allowed to "Kill" or "Open".

3. Telemetry & Heartbeat (Push Strategy)

To support the onsite dashboard (src/routes/events/.../device), the Electron app must push its status back to the server.

3.1 Heartbeat Payload (`PATCH /v3/crud/event_device/{id}`)

{
  "heartbeat": "2026-01-20T14:30:00Z",
  "status": "Online",
  "status_msg": "Presentation: 'Introduction to AE.pptx' (Slide 4/20)",
  "record_status": "Idle",
  "info_ip_list": "192.168.1.10, 10.0.0.5",
  "meta_json": {
    "cpu_usage": 12,
    "memory_free_gb": 4.2,
    "sync_progress": 100,
    "foreground_app": "PowerPoint",
    "is_fullscreen": true
  }
}

4. The "Bootstrap Paradox" Resolution

To allow unauthenticated config fetching for new devices:

Device API Key: Each device record in the DB has an api_secret_key.
Initial Header: The Electron app sends x-aether-device-key: <key> in the bootstrap request.
JWT Hand-off: The response meta will contain a short-lived JWT that the app uses to authenticate its first "Real" V3 requests.

5. Database Mapping (V3 Enriched View)

The v_event_device SQL view must be updated to include:

account_id_random (joined from account)
event_id_random (joined from event)
location_id_random (joined from event_location)
theme_name (joined from site_cfg_json via account)

3.1 KiB Raw Blame History