Air-Gapped Licensing

For devices that never connect to the internet, LicenseSeat currently supports an operator-assisted machine-file workflow:

1. Collect the target machine fingerprint on the air-gapped device.
2. Use a connected admin/service machine to call activate for that fingerprint.
3. Call machine-file for the same fingerprint.
4. Transfer the resulting machine file back via USB or other approved media.
5. Verify it locally on the air-gapped device.

This works today. It consumes a seat correctly, preserves device binding, and does not require a dedicated challenge-response protocol.

Important: LicenseSeat does not currently ship a first-class challenge-response product flow, QR ceremony, offline-activation endpoint, or dashboard wizard for air-gapped provisioning. If you need those, build the current API-assisted workflow first and treat challenge-response as future product work.

Current Supported Workflow

Step 1: Collect the fingerprint on the target machine

Your app, helper CLI, or provisioning tool should print or export the machine fingerprint from the target device.

Examples:

• A small helper app that displays the fingerprint on screen
• A CLI that writes the fingerprint to a text file for USB transfer
• A local admin page that exports fingerprint + optional device name

Step 2: Activate from a connected machine

Activation is what consumes the seat.

curl -X POST "https://licenseseat.com/api/v1/products/my-app/licenses/LICENSE-KEY/activate" \
  -H "Authorization: Bearer pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "target-machine-fingerprint",
    "device_name": "Factory PLC 07"
  }'

Step 3: Issue the machine file

Machine-file issuance does not consume an extra seat. It requires the activation from the previous step to already exist.

curl -X POST "https://licenseseat.com/api/v1/products/my-app/licenses/LICENSE-KEY/machine-file" \
  -H "Authorization: Bearer pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "target-machine-fingerprint",
    "ttl": 365,
    "include": ["license"]
  }'

The response contains the PEM-like machine-file certificate. Save it to disk and transfer it to the target system.

Step 4: Import or place the machine file on the target machine

What this looks like depends on your SDK/app:

• Newer SDKs such as C++ can verify the machine file directly.
• Older SDKs may still use signed offline tokens instead of machine files and have not migrated yet.
• A custom integration can store the certificate in your own secure local storage and verify it on startup.

Why this is secure

• Seat consumption happens first: you cannot mint unlimited offline credentials without activating.
• Fingerprint binding is preserved: the machine file is encrypted using the license key and target fingerprint.
• Tamper detection is built in: the machine file is signed with Ed25519.
• Machine files stay finite: use longer TTLs for true air-gapped systems, but not infinite ones.

Choosing TTLs for air-gapped systems

Recommended starting points:

Long TTLs are a tradeoff:

• better operational convenience
• slower revocation visibility
• slower entitlement/metadata change visibility

The underlying license expiry still wins. A machine file does not outlive the license itself.

What is not productized yet

These are sensible future improvements, but they are not current built-in features:

• Challenge-response encoded blobs
• QR-based offline activation/import ceremonies
• One-click dashboard action: “paste fingerprint → activate → download machine file”
• Batch renewal packages from the dashboard
• Dedicated offline-activation endpoints separate from activate + machine-file

Best Practices

1. Keep a documented record of which physical device maps to which fingerprint.
2. Use a friendly device_name when activating so audit logs stay readable.
3. Prefer machine files over legacy offline tokens for new air-gapped deployments.
4. Choose a TTL intentionally instead of asking for “never expires”.
5. Test the full USB/manual provisioning workflow before shipping to a remote site.