Migrating from another license manager

Moving to LicenseManager doesn’t mean sending new keys to your customers. With the API, you import each license with its current key, its customer, its expiration and its limits. Then you ship a version of your app that validates keys with LicenseManager, and your customers don’t notice anything.

This guide moves Acme Photo’s 3,000 licenses from another tool. You’ll:

1. Prepare the product, its policies and releases.
2. Map your old licenses to LicenseManager’s.
3. Import them with the API.
4. Switch your app, and run both tools during the transition.

Prepare the product

Map your licenses

For each old license, prepare the body of a license creation:

Customers’ names can’t be sent with a license. To import them, create each customer first, with POST /v1/products/{productId}/customers and their email and name: their licenses are then added to them.

Import

With an API key, create each license:

curl -X POST https://api.licensemanager.dev/v1/products/x7Kp2QaZ/licenses \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "key": "ACME-2024-8F3K-29XQ",
    "policyId": "p4Rt8LmQ",
    "expiresAt": "2027-03-01T00:00:00Z",
    "maxMachines": 2,
    "maxVersion": { "lockMajorAt": "2027-03-01T00:00:00Z", "lockMinorAt": "2027-03-01T00:00:00Z" },
    "price": { "amount": 49, "currency": "USD" },
    "meta": { "legacyId": "lic_8812" }
  }'

• Don’t send sendKey: your customers already have their keys. An import emailing 3,000 customers is the kind of mistake you can’t undo.
• Make it safe to run again: a license whose key is already imported is refused with 409 and key_taken. Treat it as done, so an interrupted import can start over.
• Check the result: compare the number of licenses in Licenses with your old tool, and look at a few of them.

What can’t be imported

• Machines. Activations of the old tool aren’t imported: each license starts with no machine. Each computer is registered the first time the new version of your app validates its key, and takes a place then. A license allowing 2 machines, used on 2 computers, keeps working on both.
• History. The old tool’s history isn’t imported. Each license starts with a license.created event dated from the import, by the API key’s name.
• Creation dates. Licenses are created at the time of the import. Keep the original date in meta if you need it.
• Last activation. Imported licenses show as Inactive until their key is validated, and don’t count toward your plan’s active licenses until then.

Switch your app

Edge cases

Keys that differ only by case, like abc-123 and ABC-123, are two different keys. Your new version of the app must send keys exactly as stored: don’t upper-case them, unless your old keys were all upper case.

Keys starting with TEST-. In a live product, the TEST- prefix is removed from the keys you send, as it marks test keys: a live key TEST-8F3K would be imported as 8F3K. In a test product, TEST- is added to every key: your app’s real keys won’t match. Test the import with a copy of your keys, and the switch of your app with test keys.

Two licenses with the same key in your old tool can’t both be imported in one product. Give one of them a new key, and send it to its customer.

Several products. Import each product’s licenses in its own product. A customer of two products is imported as two customers, one per product.

Licenses already expired. Import them with their past expiresAt, to keep their customers, and let them renew: validating their key fails with license_expired.

Email changes. The customer is matched by email: two old licenses of the same person with two emails make two customers. Merge the emails before importing when you can.