本页暂无中文版本,以下是英文原文。
Migrating to Keygate
Move customers from another licensing system to Keygate: export to CSV, import with the admin API, set per-seat quantities and switch your app.
Moving from Keygen, Cryptlex, LicenseSpring or a system you built yourself follows the same steps: recreate your plans, import your customers, and ship an app version that talks to Keygate. Most of the work is planning how your customers move over, not the import itself.
Before you start
Keygate issues its own license keys, so every customer gets a new key. Keys from your old system cannot be imported. That decides the rest of the plan:
- Create your products and plans in Keygate first. See Licensing models to map your old plans onto Keygate's license types, including plans sold per seat. If customers will subscribe through Stripe later, read Moving subscriptions first: the plan you import onto decides whether they keep their key.
- Decide on each product's license key prefix before you import. It is the first part of every key,
KGunless you change it, and a change applies only to keys issued afterwards. A prefix of its own makes new keys easy to tell apart from old ones. - Keep the old system running until most active customers have moved, so nobody is locked out by the switch.
- Edit the license email under Email Templates before you import. Every imported license sends the customer their new key, and that email is the best place to explain why they got one.
Export your customers to CSV
Export one row per license from your old system: the email, which plan it is on, when it ends, and its ID in the old system. Leave the end date empty for licenses that never end. For a plan sold per seat, add how many seats the customer paid for; leave it empty for other plans.
email,plan,expires,customer_id,seats
[email protected],pro,2027-03-01,cus_1042,
[email protected],lifetime,,cus_1043,
[email protected],team,2027-01-15,cus_1044,12Import licenses with the admin API
Create an API key with the licenses:write scope, limited to the product you are importing into. Then run this script with Node.js 18 or later, or with Bun. It creates one license per row and keeps the old ID in external_customer_id, so running it again skips anyone it already imported. For rows with seats, it then sets the license's seats.
import { readFileSync } from "node:fs";
const KEYGATE = process.env.KEYGATE_URL; // https://licenses.example.com
const API_KEY = process.env.KEYGATE_API_KEY; // kg_live_... with licenses:write
const PRODUCT_ID = process.env.PRODUCT_ID;
// Old plan name on the left, Keygate plan ID on the right.
const PLANS = {
pro: "8c1e2b9a-...",
lifetime: "41f07d3c-...",
team: "c27a5e10-...", // sold per seat
};
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };
const [, ...lines] = readFileSync("customers.csv", "utf8").trim().split("\n");
for (const line of lines) {
const [email, plan, expires, customerId, seats] = line.split(",");
// Skip customers imported by an earlier run, so the script can be run again.
const existing = await fetch(
`${KEYGATE}/api/v1/admin/licenses?external_customer_id=${encodeURIComponent(customerId)}`,
{ headers },
).then((r) => r.json());
if (existing.data.total > 0) {
console.log(email, "already imported");
continue;
}
const res = await fetch(`${KEYGATE}/api/v1/admin/licenses`, {
method: "POST",
headers,
body: JSON.stringify({
product_id: PRODUCT_ID,
plan_id: PLANS[plan],
email,
external_customer_id: customerId,
// Keep the end date from the old system. Empty means it never ends.
valid_until: expires ? `${expires}T23:59:59Z` : "",
}),
});
const body = await res.json();
if (!res.ok) {
console.log(email, `failed: ${body.error?.code}`);
continue;
}
console.log(email, body.data.license_key);
// A license on a per-seat plan starts with 1 seat. Set what the customer paid for.
if (seats?.trim()) {
const q = await fetch(`${KEYGATE}/api/v1/admin/licenses/${body.data.id}/quantity`, {
method: "POST",
headers,
body: JSON.stringify({ quantity: Number(seats) }),
});
if (!q.ok) console.log(email, `seats not set: ${(await q.json()).error?.code}`);
}
}Team licenses and per-seat plans
Seats on a per-seat plan
A license created on a per-seat plan starts with 1 seat. The script sets the seats from your CSV with POST /api/v1/admin/licenses/:id/quantity, which is also Seats bought on the license page in the dashboard. The number must be within the plan's Minimum seats and Maximum seats, or the call answers 409 QUANTITY_OUT_OF_RANGE. A license the script created but whose seats failed is skipped on the next run, so fix its seats in the dashboard. When the seats change, the license.quantity_changed webhook is sent.
This works because imported licenses are not billed by Stripe. Once a license is billed by a Stripe subscription, as described under Moving subscriptions, its seats follow the subscription instead.
Team members
Members are not imported. The license belongs to the email in the row, its owner, and the admin API can list and remove members but not add them. After the import, the owner invites their team from the customer portal. Each member who accepts gets a license key of their own, which they use in your app instead of the owner's key.
- Members exist only on SaaS and hybrid products, the types with team seats.
- Leave room for everyone: the seat limit counts the owner, so a team of the owner and nine members needs 10 seats, either the plan's Max Seats or the seats bought. An invitation cannot be accepted while no seat is free.
- Tell owners in the license email that their team members need a new invitation from the customer portal.
Switch your app to Keygate keys
Release a version of your app that activates against Keygate, following Activating licenses in your app. On first start it finds the key saved by the old version. A Keygate key starts with your product's prefix, KG unless you set another, followed by four groups of eight letters and digits: KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789. Anything else is an old key: show a short message asking for the new key from the email, with a link to the customer portal for anyone who cannot find it.
Check for the prefix of the product the app belongs to, not only KG. Team members' own keys start with the same prefix.
Customers who never update keep using the old system for as long as you run it. Shut it down once activity there has dropped to a level you are comfortable with.
Moving subscriptions
Imported licenses are not connected to the subscriptions in your old billing setup. The end date you imported keeps each customer licensed for the time they already paid for. Before it runs out, each customer starts paying through Keygate and Stripe. Which plan you imported them onto decides whether they keep their key:
- Same key: import onto a plan without a Stripe price, update period or renewals, for example a copy of your paid plan named Pro (imported), with the same limits and features. It can stay inactive so nobody buys it. The owner then sees Upgrade on the license in the customer portal, picks the paid plan and pays on Stripe Checkout. The same license moves to the paid plan, with its key and devices, and from then on follows its Stripe subscription. An expired license can still upgrade. See Upgrading a free license.
- New key: a plan's checkout link always creates a new license with a new key when the customer pays, and the imported license runs out at its end date. On a per-seat plan, add the number of seats to the link, for example
?quantity=12, so checkout starts at what they have now.
Cancel each old subscription as its customer moves, so nobody is charged twice. See Selling with Stripe.
Frequently asked questions
Can I import license keys from my old system?
No. Keygate issues a new key for every license it creates, and the admin API has no field for an existing key. Keep the old system running while customers move over, and use the license email to send each customer their new key.
How can my app tell a Keygate key from an old one?
A Keygate key is the product's prefix followed by four groups of eight letters and digits, for example KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789. The prefix is KG unless you set another one on the product. If your old keys start the same way, give the product a prefix of its own before you import.
Are team members imported with the license?
No. The import creates one license per customer, for the owner. The admin API can list and remove members but not add them, so after the import the owner invites their team again from the customer portal. Each member who accepts gets a license key of their own.
How do I import a license on a per-seat plan?
Create the license as usual, then set how many seats the customer paid for with POST /api/v1/admin/licenses/:id/quantity. A new license starts with 1 seat, and the number has to be within the plan's minimum and maximum seats.
Do imported customers get a new key when they subscribe through Stripe?
Not if you import them onto a plan without a Stripe price. The owner then uses Upgrade in the customer portal, and the same license, with the same key and devices, moves to the paid plan. A plan's checkout link always creates a new license with a new key.
最后更新 2026年10月26日