Adding licensebox to your app

One check before protected work.

Create a client for your product and trusted public keys. Before loading user files or running a protected operation, require the module that operation needs. Continue only after the check succeeds.

1. Configure once. Keep a client per process and provide your app version. Follow the chosen SDK's native dependency and storage instructions.
2. Present sign-in. Show the device verification link and user code in your UI, or use the SDK's default instructions. Keep private credentials out of logs.
3. Authorize the feature. Use the client's require/module-check operation. A local status display or usage record does not authorize work.
4. Handle failure and cleanup. Surface the stable error code, stop protected work when refused, and close clients deterministically where required.

All clients expose the same capabilities: lease checks, module authorization, local status, explicit sign-in, logout, module discovery, requests, private access links and opt-in usage counts. Exact method names and ownership rules are in each SDK's guide.

A small Go example.

For another language, choose its client above. This example uses the Go SDK's public API:

go get licensebox.dev/client@v0.7.0

import (
    "licensebox.dev/client"
    "licensebox.dev/lease"
)

lic, err := client.New(client.Config{
    Product: "YOUR_PRODUCT_ID",
    Keys: lease.Keys{
        "YOUR_KEY_ID": lease.MustKey("YOUR_PUBLIC_KEY"),
    },
    Version: version,
})
if err != nil { return err }

if _, err := lic.Require(ctx, "export"); err != nil {
    return err
}
// Protected work starts here.

Replace the placeholders with administrator-provided IDs and public verification keys. Use the Go integration guide for context, imports and full error handling.

Sign in once. Renew when needed.

On first protected use, the application presents a short code and verification link. The user opens that link on any device, confirms their email, supplies the requested purpose and accepts the product's terms. The licensed installation is the app requesting access.

In each new process, the first protected call silently attempts renewal with a three-second bound. A fresh lease can be reused within that process until expiry. SDKs do not start a background heartbeat automatically.

When the network is unavailable

Eligible transport failures and server outages can use a verified, unexpired cached lease. The product controls the offline allowance; the default is 24 hours, potentially shortened by a grant's expiry. Once it expires, the app needs a connection. Expiry alone does not require another email sign-in.

Optional checks during long-running work.

Call your SDK's heartbeat operation with the protected module to force a fresh online check. It never opens sign-in or creates a new machine identity. The result includes the verified lease and whether contact succeeded. Eligible outages preserve access only until the last signed expiry; an explicit refusal stops authorization.

Go, Python and Node also offer an explicitly started monitor. Its expiry watchdog works independently of a stalled request or observer callback. Other clients expose the primitive for your application's own timer or event loop. Follow the selected client's guide for method names and cleanup.

Your application owns safe checkpoints and shutdown. Respond to cancellation or failure by pausing or stopping protected work safely; the SDK does not kill the process.

Shared rules for machines and locations.

Machine seats

Set a seat limit per user and product; zero means unrestricted. At capacity, a completed sign-in transfers the oldest seat. Ordinary renewal never takes a transferred seat back. A displaced installation must explicitly sign in if the user chooses to move it again.

Leases are tied to the installation key and native machine binding. Copying credentials to another ordinary machine is refused. Raw native IDs remain local; cloned or spoofed system identities are a limitation, so this is not hardware attestation.

Location rules

Allow or block countries, cities, or radius areas from the admin console. These use the app connection's approximate IP location. Blocks take precedence; required location data that cannot be established refuses access. VPNs and proxies affect the apparent location.

A client offline cannot discover a new policy decision until contact or lease expiry. Seat and location refusals are retained locally until successful renewal or explicit sign-in. Configure the product policy.

Modules, trials and individual access.

A module is a feature name your app checks, such as core, export or batch. A lease names the modules the user may run:

• Free modules are available to everyone who signs in.
• Trial modules are available for a configured period after first sign-in.
• Individual grants can be permanent or expire on a date.

Let users request more access

Module discovery shows available features, descriptions and existing requests. Your app can submit a request and list the user's answers, or open a short-lived private access link. Administrators approve all or some modules, optionally until a date, or decline with a note. Approved access reaches the app at its next check.

Access links are credentials. Do not place them in analytics, logs, shared prompts or public pages.

Optional command usage

If the product enables collection, record fixed command names, outcomes and durations. Counts queue locally and are sent with renewal, with retry-safe cumulative IDs. Do not record filenames, arguments, user files, geometry or application data. Usage reporting never authorizes a feature and does not create a background process.

Make refusals understandable.

Use the selected SDK's stable error code and stop protected work. The table describes shared behavior; language-specific exception names live in each README.

The shared HTTP protocol.

Official clients handle signed HTTPS requests, native identity, verification and persistence. If you maintain a client, work from the exact shared specification and run its complete conformance suite. API paths retain /v1; signed proofs and leases use format v2.

A signed lease, kept locally.

The SDK verifies the lease's signature, trusted key, product, installation, native machine binding, modules and expiry. Parsing JSON does not authorize an operation. The client also retains the latest observed time so a clock rollback cannot revive an expired lease.

Keep the installation key private and allow the SDK to manage its storage. Logout removes licensing state and queued usage while preserving the installation identity and saved clock. Follow the selected client's storage and cleanup requirements.

Two command-line tools. Different jobs.

Licensebox manages access. It does not collect payments or handle billing; commercial arrangements stay with the product's team.