Authentication - Qaptly Docs

Security Model

UPP uses a “First-Time Approval + Pre-Shared Key” security model that balances security with ease of use.

Key Principles

User Approval Required - New pilots need explicit user approval
Key-Based Authentication - Known pilots authenticate with pre-shared keys
Internal Network Only - Designed for local network deployment, not public internet
Key Persistence - Keys are stored securely for future connections

Authentication Flow

First-Time Connection

When a pilot connects for the first time (without a key):

1. Pilot Sends Register

{
  "type": "register",
  "payload": {
    "pilot": {
      "id": "my-pilot-001",
      "name": "My WiFi Controller",
      "version": "1.0.0",
      "vendor": "My Company"
    },
    "auth": {},  // Empty auth for first time
    "capabilities": [...]
  }
}

2. Qaptly Shows Approval Dialog

A dialog appears in Qaptly Desktop:

┌─────────────────────────────────────────────┐
│  New Pilot Connection Request               │
├─────────────────────────────────────────────┤
│                                             │
│  Name: My WiFi Controller                   │
│  ID: my-pilot-001                           │
│  Vendor: My Company                         │
│                                             │
│  Capabilities:                              │
│  • wifi.scan - Scan WiFi Networks           │
│  • wifi.connect - Connect to WiFi           │
│  • wifi.status - Get WiFi Status            │
│                                             │
│  ⚠️  Only approve pilots from trusted       │
│      sources                                │
│                                             │
│  Auto-reject in 120 seconds                 │
│                                             │
│  ┌─────────┐  ┌──────────────────────────┐ │
│  │ Reject  │  │ Approve                   │ │
│  └─────────┘  └──────────────────────────┘ │
└─────────────────────────────────────────────┘

3. User Decision

If User Approves:

{
  "type": "register_response",
  "payload": {
    "success": true,
    "pilotId": "my-pilot-001",
    "assignedKey": "abc123-generated-key-xyz789",
    "message": "Pilot approved and registered",
    "heartbeat": {
      "interval": 30000,
      "timeout": 90000
    }
  }
}

If User Rejects:

{
  "type": "register_response",
  "payload": {
    "success": false,
    "error": {
      "code": "USER_REJECTED",
      "message": "User rejected this pilot"
    }
  }
}

4. Pilot Stores Key

Important: Save the assignedKey for future connections!

# Save key to config file
config = {
    "pilot_id": "my-pilot-001",
    "auth_key": "abc123-generated-key-xyz789"
}
with open("pilot_config.json", "w") as f:
    json.dump(config, f)

Subsequent Connections

For known pilots with valid keys:

1. Pilot Sends Register With Key

{
  "type": "register",
  "payload": {
    "pilot": {
      "id": "my-pilot-001",
      "name": "My WiFi Controller",
      "version": "1.0.0"
    },
    "auth": {
      "key": "abc123-generated-key-xyz789"  // ← Use saved key
    },
    "capabilities": [...]
  }
}

2. Qaptly Verifies Key

Key is verified against stored hash. No user interaction needed.

3. Automatic Approval

{
  "type": "register_response",
  "payload": {
    "success": true,
    "pilotId": "my-pilot-001",
    "message": "Pilot registered successfully",
    "heartbeat": {
      "interval": 30000,
      "timeout": 90000
    }
  }
}

Pre-Shared Keys (Advanced)

For production deployments, you can pre-configure keys before the first connection.

Use Cases

Embedded devices: Deploy with pre-configured keys
CI/CD pipelines: Automated test pilots
Fleet management: Deploy multiple pilots at once

Implementation

1. Generate Key Manually

In Qaptly Desktop’s pilot extension config file, add:

{
  "authorizedPilots": {
    "production-pilot-001": {
      "name": "Production WiFi Controller",
      "key": "pre-shared-secret-key-12345",
      "authorizedAt": "2026-01-21T10:00:00.000Z"
    }
  }
}

2. Deploy Key to Pilot Device

{
  "pilot_id": "production-pilot-001",
  "auth_key": "pre-shared-secret-key-12345"
}

3. Pilot Connects

The pilot will be approved automatically without user interaction.

Pre-shared keys are useful for:

Production environments
Automated testing
Headless deployments
Fleet management

Security Best Practices

1. Internal Network Only

UPP is designed for local network deployments: ✅ Correct: ws://<qaptly_desktop_ip>:18765/upp (local network IP like 192.168.1.100) ❌ Never: Expose to public internet or bind to public IP addresses Security Guidelines:

Deploy only on trusted internal networks
Use firewall rules to restrict access if needed
Consider VPN for remote pilot access
Do not port-forward 18765 to the internet

2. Key Storage

Do NOT:

Commit keys to version control
Share keys publicly
Use same key for multiple pilots
Store keys in plaintext in production

Do:

Use environment variables or config files
Set proper file permissions (chmod 600)
Use different keys for development/production
Rotate keys periodically (optional)

3. Pilot ID Uniqueness

Choose unique pilot IDs:

Format: <vendor>-<type>-<instance>
Examples:
  - acme-wifi-controller-001
  - mycompany-sensor-hub-lab-01
  - test-pilot-dev-instance

4. Version Information

Always include accurate version numbers:

{
  "pilot": {
    "id": "my-pilot-001",
    "version": "1.2.3",  // Semantic versioning
    "name": "My WiFi Controller v1.2"
  }
}

This helps users identify outdated pilots.

Key Management

Key Generation

Qaptly generates keys using:

256-bit random bytes
Hex encoding
Cryptographic random number generator

Key Storage

Keys are stored with:

SHA-256 hashing (not plaintext)
Secure file permissions
Backup mechanism

Key Rotation (Optional)

To rotate a key:

User: Revoke the old pilot in Qaptly Desktop
Pilot: Connect without key (first-time flow)
User: Approve and receive new key
Pilot: Save and use new key

Error Codes

Authentication Errors

Code	Scenario	Solution
`AUTH_FAILED`	Invalid or expired key	Reconnect without key to get new one
`USER_REJECTED`	User clicked “Reject”	Request user to approve in Qaptly
`APPROVAL_TIMEOUT`	User didn’t respond within 120s	Try connecting again
`DUPLICATE_PILOT_ID`	Pilot ID already registered	Change pilot ID or disconnect other pilot

Handling AUTH_FAILED

async def handle_register_response(response):
    payload = response.get("payload", {})

    if not payload.get("success"):
        error = payload.get("error", {})

        if error.get("code") == "AUTH_FAILED":
            print("⚠️  Key verification failed")
            print("💡 Reconnecting without key...")

            # Delete stored key
            os.remove("pilot_config.json")

            # Reconnect without key (first-time flow)
            await reconnect_without_key()

Reconnection After Disconnect

If your pilot disconnects (network issue, restart, etc.):

Within 5 Minutes

Reconnect with same key
Qaptly remembers your registration
No user approval needed
Event subscriptions are restored

After 5 Minutes

Pilot is unregistered
Must register again with key
Same as “Subsequent Connections” flow
May need user approval if key is invalid

Testing Authentication

Test 1: First-Time Connection

# Run pilot without key
python wifi_pilot.py

Expected:

“Waiting for user approval…”
Dialog appears in Qaptly
After approval: “Received assignedKey”

Test 2: Reconnection

# Run pilot with saved key
python wifi_pilot.py --config pilot_config.json

Expected:

Immediate success
No user interaction

Test 3: Invalid Key

# Modify key in config to invalid value
python wifi_pilot.py --config pilot_config.json

Expected:

AUTH_FAILED error
Pilot should handle gracefully

Example: Complete Auth Flow

import json
import os

class AuthManager:
    def __init__(self, config_file="pilot_config.json"):
        self.config_file = config_file
        self.pilot_id = "my-pilot-001"
        self.key = None
        self.load_key()

    def load_key(self):
        """Load key from config file if it exists"""
        if os.path.exists(self.config_file):
            with open(self.config_file, "r") as f:
                config = json.load(f)
                self.key = config.get("auth_key")
                print(f"✅ Loaded key from {self.config_file}")
        else:
            print("ℹ️  No key found, will request new one")

    def save_key(self, key):
        """Save key to config file"""
        config = {
            "pilot_id": self.pilot_id,
            "auth_key": key
        }
        with open(self.config_file, "w") as f:
            json.dump(config, f, indent=2)

        # Set secure file permissions (Unix)
        os.chmod(self.config_file, 0o600)
        print(f"💾 Saved key to {self.config_file}")

    def delete_key(self):
        """Delete stored key"""
        if os.path.exists(self.config_file):
            os.remove(self.config_file)
            self.key = None
            print(f"🗑️  Deleted {self.config_file}")

    def get_auth_payload(self):
        """Get auth payload for registration"""
        if self.key:
            return {"key": self.key}
        else:
            return {}

    def handle_register_response(self, payload):
        """Handle registration response"""
        if payload.get("success"):
            assigned_key = payload.get("assignedKey")
            if assigned_key:
                self.save_key(assigned_key)
                self.key = assigned_key
            return True
        else:
            error = payload.get("error", {})
            if error.get("code") == "AUTH_FAILED":
                print("❌ Authentication failed, deleting key")
                self.delete_key()
            return False

# Usage
auth = AuthManager()

# Build registration payload
payload = {
    "pilot": {
        "id": auth.pilot_id,
        "name": "My WiFi Controller",
        "version": "1.0.0"
    },
    "auth": auth.get_auth_payload(),  # Empty or with key
    "capabilities": [...]
}

Next Steps

Protocol Reference

Complete message specifications

Capabilities

Define capabilities with JSON Schema

Quick Start

Build your first pilot

Examples

Working implementations

​Security Model

​Key Principles

​Authentication Flow

​First-Time Connection

​1. Pilot Sends Register

​2. Qaptly Shows Approval Dialog

​3. User Decision

​4. Pilot Stores Key

​Subsequent Connections

​1. Pilot Sends Register With Key

​2. Qaptly Verifies Key

​3. Automatic Approval

​Pre-Shared Keys (Advanced)

​Use Cases

​Implementation

​1. Generate Key Manually

​2. Deploy Key to Pilot Device

​3. Pilot Connects

​Security Best Practices

​1. Internal Network Only

​2. Key Storage

​3. Pilot ID Uniqueness

​4. Version Information

​Key Management

​Key Generation

​Key Storage

​Key Rotation (Optional)

​Error Codes

​Authentication Errors

​Handling AUTH_FAILED

​Reconnection After Disconnect

​Within 5 Minutes

​After 5 Minutes

​Testing Authentication

​Test 1: First-Time Connection

​Test 2: Reconnection

​Test 3: Invalid Key

​Example: Complete Auth Flow

​Next Steps

Protocol Reference

Capabilities

Quick Start

Examples

Security Model

Key Principles

Authentication Flow

First-Time Connection

1. Pilot Sends Register

2. Qaptly Shows Approval Dialog

3. User Decision

4. Pilot Stores Key

Subsequent Connections

1. Pilot Sends Register With Key

2. Qaptly Verifies Key

3. Automatic Approval

Pre-Shared Keys (Advanced)

Use Cases

Implementation

1. Generate Key Manually

2. Deploy Key to Pilot Device

3. Pilot Connects

Security Best Practices

1. Internal Network Only

2. Key Storage

3. Pilot ID Uniqueness

4. Version Information

Key Management

Key Generation

Key Storage

Key Rotation (Optional)

Error Codes

Authentication Errors

Handling AUTH_FAILED

Reconnection After Disconnect

Within 5 Minutes

After 5 Minutes

Testing Authentication

Test 1: First-Time Connection

Test 2: Reconnection

Test 3: Invalid Key

Example: Complete Auth Flow

Next Steps