Skip to content

OEM Stock Licensing

An OEM partner receives a prepaid device-right pool. The runtime activates a device automatically from that pool. End users do not need a HeimerClean account, email address or key-entry screen. HeimerClean does not need the partner's customer directory or customer identifiers.

What consumes stock

Event Result
First activation of a new device in a pool One right consumed; that device's term starts now
Retry, lost response, restart or same-device activation Existing right returned; no additional consumption
Regular lease renewal Original end date retained; no additional consumption
Empty stock New devices refused; valid existing devices can renew
Paused pool New devices refused; valid existing devices can renew
Revoked pool New activation and online renewal refused
Expired device term Renewal refused; another right is never silently spent

The default device term is 365 days, configurable by the platform operator at pool creation. Unused rights have no running device term. Stock is consumable: expiry/uninstall does not automatically refund a right. Hardware changes and paid term extensions require an operator-reviewed process; this pilot does not automatically transfer rights.

1. Allocate the partner's pool

These are operator/server operations. Use the existing portal bearer session with platform-admin access. The source channel must be an OEM partner workspace. Never ship that bearer in the partner installer.

POST https://api.heimerclean.com/web/admin/oem-stock/pools

{
  "source_channel_node_id": 7,
  "request_id": "stock-order-20261020-001",
  "partner_id": "your-vendor",
  "protocol_id": "YOUR-OEM-PROTOCOL",
  "count": 1000,
  "duration_days": 365
}

The response includes a pool_id, counts and a one-time activation_token. Store that capability in protected deployment storage. Retrying the same request ID returns the existing pool without revealing the original token or creating more rights. If the first response was lost, an operator can rotate the activation token.

Each pool holds at most 5,000 prepaid rights to bound its atomic claim ledger. Further pools can use the same partner/protocol; existing devices renew against their original pool. Inventory returns the latest 100 pools and includes this limit. This ledger does not automatically create invoices or collect payments.

2. Configure automatic activation

The partner's installer/process supervisor supplies both values to the runtime's child environment once:

  • HC_OEM_STOCK_POOL_ID: the assigned pool ID.
  • HC_OEM_STOCK_ACTIVATION_TOKEN: its limited activation capability.

Keep --partner-id and --protocol-id aligned with the pool. The host removes the environment values, stores the token through Windows Credential Manager/DPAPI and saves the pool ID in its isolated profile. Do not put the token on a command line or print it.

With no license configured, the runtime starts bounded background activation. Your C++ UI polls GET /v1/license; stock_activation_error, if present, is a sanitized error code. Failed first activation grants no provisional trial. Startup retains existing configured licenses and never silently changes pools.

For explicit host-driven setup, use the existing DLL request function with POST /v1/license/activate-stock:

{
  "pool_id": "0123456789abcdef",
  "activation_token": "REPLACE_WITH_THE_ISSUED_ACTIVATION_TOKEN"
}

This local call needs the protected runtime session. Busy maintenance or another activation prevents license changes. The generic C ABI is unchanged.

3. Device rights and offline operation

The runtime sends partner/protocol and technical device identity to the cloud. Requests reject email, customer_id, hostname and other unknown fields. One atomic claim enforces capacity and duplicate-device protection. Retry an interrupted response for the same device.

The right is RSA-signed and bound to the OEM audience, partner, protocol and device. Normal desktop keys do not grant OEM stock rights. Normal desktop verification rejects OEM-stock leases. Existing individual-stock login requirements and offline policy remain unchanged.

OEM leases renew without customer login. Their signed offline window remains at most seven days, capped by the original device end date. Online refresh propagates revocation to a cooperative client; an offline client can retain a previously signed lease until expiry. Stock does not grant a full-year offline lease.

4. Inventory and controls

Endpoint Access / purpose
GET /web/admin/oem-stock/pools Platform operator: pool inventory
GET /web/channel/oem-stock/pools Partner owner/finance roles: current workspace inventory only
POST /web/admin/oem-stock/pools/{pool_id}/credits Operator: top up with request_id and count; retry does not duplicate credit
PATCH /web/admin/oem-stock/pools/{pool_id} Operator: status is active, paused or revoked
POST /web/admin/oem-stock/pools/{pool_id}/rotate-token Operator: replace the activation capability

Inventory exposes counts, scope, status and term, never device keys, token hashes or the claim ledger. Rotating the token blocks old-token activation; existing devices renew with their own device-bound key.

The activation capability is not an unextractable secret: a local administrator can inspect client processes. It permits bounded stock claims only, not stock creation, another partner's inventory or portal administration. Protect distribution, monitor counts and pause/rotate if a package is abused.

Errors and contracts

  • HC_OEM_STOCK_EMPTY: allocate stock or provision another pool.
  • HC_OEM_STOCK_PAUSED: new devices are paused.
  • HC_OEM_STOCK_DENIED: check pool/token, partner/protocol or revocation.
  • HC_OEM_DEVICE_CHANGED: retain the key and request identity review; do not consume fresh rights repeatedly.
  • HC_LICENSE_EXPIRED: original term ended; no automatic new purchase.
  • HC_OEM_SIGNING_UNAVAILABLE: retry later; no unsigned right is granted.
  • HC_LICENSE_ACTIVATION_RATE_LIMIT / HC_RATE_LIMITED: back off before retrying the same device.

Local OpenAPI · Cloud stock OpenAPI · C++ integration · Acceptance gates

This remains an integration pilot. Production publisher signing, clean Windows/partner-app acceptance and customer rollout remain separate gates.