Three questions before you export
Are the keys stored in plaintext? The import needs the key string. If your table holds only a hash, you cannot import it. Keep the old server running for those buyers and let Clavem issue keys for new sales.
Are keys verified offline? If your keys are signed and the app checks the signature with a public key inside the binary, installed copies need no server at all. Importing those keys still lets Clavem track them. Keep the offline check in the new build as a fallback so no one is locked out during the switch.
Which hostname do installed apps call? Every build you shipped has your old URL in it. A platform migration forces an app update, because you do not control the platform’s host. You do control yours, so you can leave it up and forward its requests to Clavem. That is the main advantage you have, and it is described below.
Export the keys with their devices
The simplest shape is one row per device: repeat the license on each row and put one device on it. Clavem reads repeated keys as one license with several devices, and a license with no devices appears once with empty device cells. This query runs on SQLite as written, and works on Postgres and MySQL with your own table and column names:
select l.license_key as key,
l.email,
l.name,
l.max_devices as activation_limit,
l.expires_at,
l.created_at,
case when l.revoked_at is not null then 'disabled' end as status,
d.machine_id as instance_id,
d.label as instance_name,
d.activated_at as instance_created_at
from licenses l
left join devices d on d.license_id = l.id and d.deactivated_at is null
order by l.id, d.id;
Write it out as CSV with a header, for example sqlite3 -csv -header app.db "…" > licenses.csv. Leave deactivated devices out, as the join above does, or they take seats.
Two traps showed up when the output was run through Clavem’s file parser. First, SQLite’s -json mode wrote the devices aggregate as a JSON string, even when wrapped in json(), and Clavem silently skipped it, so the licenses imported with no devices. Use the join above, or on Postgres use json_agg, which gives a real array, as shown in Import existing licenses. Second, joining device names with a separator breaks if a name contains |, so one row per device is safer than group_concat.
Fix what the importer refuses
Each row is checked on its own. A bad row is listed with its position and the rest import. These values were refused when tested:
| Your value | Result | Fix |
|---|---|---|
1709546400 (Unix seconds) |
createdAt must be an ISO 8601 date |
Convert to 2024-03-04T10:00:00Z. |
0000-00-00 00:00:00 (MySQL) |
refused | Write an empty cell. |
9999-12-31 as “never” |
refused, years run 1990 to 2200 | Write an empty cell. |
31/01/2027 |
refused | Use 2027-01-31. |
activation_limit 0 |
must be a positive number, or -1 for unlimited |
Use -1 for unlimited. |
status revoked |
status must be inactive, active, expired or disabled |
Map it to disabled. |
| a key under 12 characters | key is shorter than 12 characters |
Cannot be imported as is. |
| empty email | email is required |
Fill it in. |
Accepted without changes: 2024-03-04 10:00:00 (read as UTC), 2024-03-04 10:00:00.123456+00 and 2024-03-04T10:00:00+0200. Keys are matched without regard to capitals, so 7QX2M-… and 7qx2m-… are one license. Two rows that differ only in case count as the same key, and the second is merged into the first.
A license with more devices than its limit imports with all of them, and the result says so. New activations are refused until a seat is freed, which is usually what you want for a key that was over its limit in the old system.
Check the plan limit before you run it
Only active or inactive licenses that have not expired count against your plan. Expired and disabled ones do not, and a batch that would pass the limit is refused whole, with 402 plan_limit, before anything is written. A made-up example: a table of 2,400 keys with 1,350 live, 700 expired and 350 disabled adds 1,350 to the count. The Indie plan covers 1,000 active licenses and Studio covers 10,000, so the live keys need Studio at $79 a month. Importing the 1,050 expired and disabled rows first costs nothing against the limit. The limits are on the pricing page.
Import
Use the file import in the dashboard, which reads the file in your browser, shows how each header was mapped and the first five rows, and sends batches of 500. To script it, create a management API key and call POST /v1/admin/licenses/import with up to 500 licenses per request. The script in the import docs does this and is safe to run twice, because a key already in your account only gains devices it lacked. A product_id that is not yours refuses the whole request with 404.
Keep old builds working with a forwarder
If devices went in with their old machine ids as instance_id, an old app can ask your old endpoint and your endpoint can ask Clavem. This sketch shows the idea with an invented request format; change the input and output to match yours. It was run against the public demo key, and answered ok for the key alone and not ok for an unknown machine id and for an unknown key.
import { createServer } from 'node:http';
createServer(async (req, res) => {
if (req.method !== 'POST' || req.url !== '/api/check') { res.writeHead(404); return res.end(); }
let raw = '';
for await (const chunk of req) raw += chunk;
const { key, machine } = JSON.parse(raw); // what the old app sends
const r = await fetch('https://clavem.io/v1/licenses/validate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ license_key: key, ...(machine && { instance_id: machine }) }),
});
const v = await r.json();
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ ok: v.valid === true, expires: v.license_key?.expires_at ?? null })); // what the old app expects
}).listen(process.env.PORT ?? 8080);
Each request counts against Clavem’s License API limits of 120 requests per 60 seconds per IP address, and your server is now the one IP address. If you have many installed copies, cache answers for a few minutes. New builds should call Clavem directly, as in the API reference.
Cut over without issuing twice
Your old server probably creates keys from Stripe webhooks. Clavem issues keys only for Stripe products you have mapped, so do the mapping at the moment you switch off your own handler. If both run, one purchase produces two keys. Then connect Stripe as in Connecting Stripe and make one test purchase.
Subscription keys need a decision. Imported keys have no Stripe subscription, so renewals do not touch them. Import them with an expires_at equal to the end of the paid period and move it with PATCH /v1/admin/licenses/:id as people renew, or let buyers subscribe through a new Stripe link and get a new key.
Rollback
Importing reads your database and writes only to Clavem. Keep the old server and its tables, read-only, until the last build that calls it has gone. Because new and old builds use different hosts, you can return a build to the old endpoint with a settings change. If you need your data back out, Clavem’s Licenses screen exports every key, buyer and status as CSV.
Questions
Can I import keys that I only stored as hashes?
No. The import needs the key string, because Clavem stores it as given and matches it when the app sends it. With hashed keys, keep your server answering the old builds, and issue new keys from Clavem for new sales.
Why did my JSON import show no devices?
The importer reads devices only from a real array, or from instance columns in a CSV. A JSON string that contains an array is silently skipped. The preview says the file lists no devices when that happens.
What does a never-expires license look like in the file?
An empty expires_at. A far-future sentinel such as 9999-12-31 is refused, because the importer accepts years from 1990 to 2200.