Integration Guide

How to embed MeshOptixIQ licensing in a Python application — including key setup, reading plan data, gating features, and handling offline scenarios.

1. License Key Setup

MeshOptixIQ resolves the license key from the following sources, in order:

1. Environment variable — MESHOPTIXIQ_LICENSE_KEY
2. License file — ~/.meshoptixiq/license.key (one key per line; first non-empty line is used)

Environment Variable (Docker / CI)

export MESHOPTIXIQ_LICENSE_KEY="mq-pro-xxxxxxxx"

License File (Persistent Installations)

mkdir -p ~/.meshoptixiq
echo "mq-pro-xxxxxxxx" > ~/.meshoptixiq/license.key
chmod 600 ~/.meshoptixiq/license.key

2. How Verification Works

License verification is multi-layered to ensure reliability in both online and offline environments.

1. Key resolution — The verifier reads the license key from the environment variable or license file at startup.
2. Server validation (24h cache) — On first use and every 24 hours, the verifier sends an HMAC-signed request to the licensing API. The server checks expiry, device binding, and plan status, then returns an RSA-signed response containing the plan and feature flags.
3. Local state cache — The signed response is written to an encrypted local state file. On subsequent calls within the 24-hour window, the verifier reads from this cache without hitting the network.
4. 72-hour grace period — If the server is unreachable during a scheduled check, the cached state remains valid for up to 72 hours. The application continues operating normally; a warning is printed on every command.
5. Grace expiry — After 72 hours without a successful server contact, the application enters restricted mode. All Pro/Enterprise features are disabled until connectivity is restored. Community-tier features always remain available.

3. Reading Plan and Features

CLI

meshq license info

# Example output:
Plan:    Pro
Status:  Active
Expires: 2027-06-30 (491 days remaining)
Device:  a3f8c1d2e4b5... (1/5 registered)

Feature Flags:
  api_access          true
  firewall_queries    true
  whatif_simulation   true
  mcp_server          true
  redis_clustering    true
  rbac                true
  netbox_sync         true
  audit_logging       true
  oidc_sso            false
  soar_webhooks       false

Device Limits:
  max_managed_devices    5
  max_network_devices    750

Python API

The verifier module exposes two public functions:

from network_discovery.licensing import verifier

# Current plan name (str): "community" | "starter" | "pro" | "enterprise"
plan = verifier.get_plan()

# Feature flags and device limits (dict)
features = verifier.get_features()
print(features["max_network_devices"])  # e.g. 750 for Pro
print(features["api_access"])           # True / False

4. Feature Gating Pattern

Use check_feature() from gates.py to gate functionality at runtime. The function raises FeatureNotAvailableError when the current plan does not include the requested feature.

from network_discovery.licensing.gates import check_feature, FeatureNotAvailableError

plan = verifier.get_plan()

try:
    check_feature(plan, "api_access")
    # proceed with API operation
except FeatureNotAvailableError as exc:
    print(f"Upgrade required: {exc}")
    sys.exit(1)

Demo Mode Bypass

When MESHOPTIXIQ_DEMO_MODE=true is set, all feature gates return True regardless of plan. Always check the environment variable before calling check_feature() to avoid stale compiled-module behaviour:

import os

if not os.environ.get("MESHOPTIXIQ_DEMO_MODE"):
    check_feature(plan, "firewall_queries")

Feature Flag Reference

5. Device Fingerprinting

Each paid plan has a maximum number of registered devices (distinct machines that have validated the same license key). The verifier generates a hardware fingerprint from a combination of:

• MAC address of the primary network interface
• OS hostname
• CPU architecture and OS platform

This fingerprint is sent with every validation request. If the device is new and the plan limit has not been reached, it is registered automatically. If the limit is already reached, the validation returns a 409 Device Limit Exceeded error.

6. Offline / Grace Period

The verifier's behaviour when it cannot reach the licensing server:

• 0–72 hours offline: Application continues normally. A warning is printed on every meshq command showing hours remaining in the grace period.
• 72+ hours offline: The application enters restricted mode. Pro/Enterprise features are disabled. Community-tier functionality (basic discovery, topology) remains available.
• Reconnection: Validation resumes automatically on the next scheduled check (every 24 hours) or on application restart. Full functionality is restored immediately after a successful check.

Diagnosing Grace Period Issues

meshq license info

# If in grace period:
# Status:  WARNING — Offline grace period active (48h 12m remaining)
# Last validated: 2026-02-22 09:14 UTC (23h 48m ago)

# Trigger an immediate validation check:
meshq license info --refresh

Common causes of unexpected grace period activation:

• Firewall rules blocking outbound HTTPS to api.meshoptixiq.com (port 443)
• DNS resolution failures in air-gapped or proxied environments
• System clock skew greater than 5 minutes (HMAC timestamp validation fails)
• Proxy requiring authentication that the verifier does not send

7. Troubleshooting