Licensing¶

Normal Framework devices require a license to operate. This page explains how licensing works, how to activate a device, and how to set up zero-touch auto-provisioning for enterprise deployments.

License Flow Overview¶

stateDiagram-v2
    [*] --> Unlicensed
    Unlicensed --> Activated : Admin creates license & activation
    Unlicensed --> Licensed : Auto-provision (enterprise)
    Activated --> Licensed : Device links activation code
    Licensed --> Licensed : Periodic renewal
    Licensed --> Unlicensed : License revoked or expired

There are two paths to get a device licensed:

1. Manual activation -- an admin creates a license in the portal and the device links it using an activation code.
2. Auto-provision -- enterprise tenants can generate a secret key that allows devices to self-register and obtain a license automatically.

Manual Activation¶

Manual activation uses a short-lived activation code to bind a license to a device.

sequenceDiagram
    participant Admin as Portal Admin
    participant Portal as Online Service
    participant Device as NF Device

    Admin->>Portal: Create License
    Admin->>Portal: Activate License (select instance)
    Portal-->>Admin: Activation code (8 characters, valid 15 min)
    Admin->>Device: Enter activation code
    Device->>Portal: LinkLicense(code, machine_id)
    Portal-->>Device: License JWT + acknowledge token
    Device->>Portal: AcknowledgeLicense(ack_token)
    Portal-->>Device: Confirmed
    Note over Device: Device is now licensed

1. An admin creates a license in the Normal portal and activates it for a specific instance.
2. The portal generates an activation code (8 characters, valid for 15 minutes).
3. The admin enters the code on the device. The device calls LinkLicense, which returns a license JWT and an acknowledge token.
4. The device confirms receipt by calling AcknowledgeLicense. This prevents the code from being rolled back.

Auto-Provision (Enterprise)¶

Enterprise tenants can enable zero-touch provisioning so that new devices automatically register and obtain a license on first boot.

sequenceDiagram
    participant Admin as Portal Admin
    participant Portal as Online Service
    participant Device as NF Device

    Admin->>Portal: Generate auto-provision key
    Portal-->>Admin: Secret key
    Note over Admin,Device: Configure device with AUTO_PROVISION_KEY
    Device->>Portal: AutoProvision(key, machine_id)
    Portal-->>Device: License JWT + instance UUID
    Note over Device: Device is licensed and online

Setup¶

1. In the Normal portal, navigate to your enterprise tenant and generate an auto-provision key.
2. Set the AUTO_PROVISION_KEY environment variable on the device to the generated key.
3. On startup, if the device has no license, it will automatically contact the portal and provision itself.

Behavior¶

• On startup with no license, the device retries auto-provision with exponential backoff (up to 5 attempts).
• If provisioning fails, the device retries every 15 minutes in the background.
• If the portal returns a permanent error (invalid key, wrong tenant type), retries are disabled to avoid unnecessary traffic.
• Auto-provision is idempotent -- if a device with the same hardware fingerprint already exists in the tenant, the portal re-issues the existing license rather than creating a duplicate.

Revoking¶

To stop new devices from auto-provisioning, revoke the key in the portal. Existing devices keep their licenses; only new registrations are blocked.

License Renewal¶

Once licensed, devices periodically renew their license JWT to keep it current.

stateDiagram-v2
    state "Licensed" as L
    state "Check Every 15 min" as C

    L --> C
    C --> L : Renewal successful
    C --> L : License still valid
    C --> Unlicensed : Portal says invalid

• Every 15 minutes, the device checks its license status.
• If the license is approaching expiration, the device calls ReIssueLicense to get a fresh JWT.
• If the portal reports the license as invalid, the device clears its local license and stops licensed services.
• Enterprise devices with an auto-provision key will automatically re-provision if they lose their license.

License Types¶

• Subscription licenses are tied to a Stripe subscription. When the subscription ends, the license enters a 14-day grace period before services are de-provisioned.
• Enterprise licenses are perpetual as long as the tenant is active. The JWT is refreshed periodically but the license itself does not expire.
• Demo licenses have a fixed expiration and cannot be renewed.

Environment Variables¶