Originally published on the PermitCore blog.
Moving to a new licensing provider does not have to mean sending every customer a new key. The key string can stay the same. What changes is the plan around it: how the application talks to the new system, how entitlement data is mapped, and how verification is trusted from the first release that points at the new endpoint.
Start with a sample you own and a rollback plan. Treat key lookup, device registrations, offline proofs, payments and customer identity as separate pieces, and move each one on purpose.
Keep the key when the lookup can be reproduced
The PermitCore CSV import wizard works from your existing key strings. It hashes each key in the browser, and the server then applies its own HMAC lookup protection, so the plaintext never needs to be stored for lookup to work. If you prefer to script it, the API importer accepts the documented SHA-256 input.
Keep the exact original value and its encoding. Case, whitespace and separators matter, because the server hashes the plaintext bytes you supply instead of inventing a new key format. Before you roll out a client update, check a few real old keys against a migrated record that you own.
If your source system stored keys in a form you cannot read back, such as a vendor-specific salted hash or an encrypted blob, work out which verifiable lookup material you actually hold. Server-side migration is the right place for that step. Keep any privileged import credential on the server and out of customer software.
Map products and policy before importing
Use Licenses → Import, choose the source preset that matches your export, and map the columns explicitly. Match each row to the correct PermitCore product, then check expiry, trial state, features, device cap, node-locking and customer association one by one rather than assuming every source field means the same thing.
The API takes up to 500 rows per batch and reports a per-row outcome: Created, Duplicate or ValidationFailed. Rows commit independently, so a large import can be done in stages, and you can keep the results to reconcile any duplicate or failed rows before you retry them.
Version limits use dotted-numeric versions, and dates deserve a deliberate conversion, including what timezone they mean. The import reference lists the current column mapping and API fields. Anything outside that mapping can be applied afterwards through the normal administration workflow.
Plan device activations on purpose
InitialActivations seeds the used count for a key, anywhere from zero up to its activation limit. Pick that number together with your re-enrollment policy: an installation that registers against the new system enrolls as a fresh device, so test three cases before the real cutover: a partly occupied key, an existing installation, and a genuinely new device.
Floating licenses start fresh in the new system, with a new checkout and a returned deadline for each seat. The capacity guide and the floating lifecycle docs walk through that flow.
Choose how keys are recovered later
The import wizard offers optional passphrase encryption. If you turn it on, you keep ciphertext that an authorised person can reveal later with that passphrase. Lookup and validation work either way. Keep your authorised source export somewhere safe if you want a recovery path for the original keys.
Licenses issued by the PermitCore Store have their own server-managed delivery and recovery path. The exit and recovery plan shows which artifacts matter for which situation.
Ship the client update deliberately
Importing data prepares the new system; your next application release is what points users at it. Ship a version that calls the new endpoint and checks the new product scope. If your app already keeps the customer's key in its settings, reuse that stored value so people are not asked to retype it. Implement and test that storage step, since it lives in your app.
For offline use, plan new signed proofs from the new system. The official SDKs verify them against trusted public keys that you configure yourself, so include that configuration in the same release, and keep private signing and Admin keys out of the client. Signing and trust rollout covers how to stage a change of trusted keys.
Run an owned pilot where you can watch old and new decisions side by side. Write down the cutover and rollback conditions, avoid running both systems for the same customer by accident, and check what an older client does once the original endpoint is retired.
Keep payments on their own track
License import is about entitlements. Card tokens, mandates, provider subscriptions and store order history are a payment-provider topic, so handle them as a separate, approved process with that provider and coordinate access dates so nobody is charged twice. If you use the PermitCore Store, changing the vendor's selected provider applies to new checkouts, and existing purchases keep the provider they were bought with. The payment lifecycle guide explains how fulfillment follows each purchase.
Pre-cutover checklist
- Reconcile row counts, duplicates, failures and product mapping between the source and the import.
- Test existing key strings, wrong-product rejection, expiry and your device re-enrollment policy.
- Test the app update, the retained key setting, the new trust configuration and offline recovery.
- Keep billing changes, customer communication and rollback under separate control.
Have you moved a licensing system before? Which step took the most care: the key lookup, the client rollout, or payments?
Top comments (0)