Three cases, three answers
People ask to move a license for three different reasons, and each needs a different response.
| Case | Old computer | Who acts | Result |
|---|---|---|---|
| New computer, same buyer | Still works | The buyer, in the app | Seat freed, new device activated |
| Old computer is dead, stolen or sold | Not reachable | The buyer on the device page, or you | Seat removed remotely |
| License passes to another person | Any | You decide, by policy | New license or an agreed handover |
The first two are mechanical and should need no email to you. The third is a policy decision, and licensing software cannot make it for you.
Case 1: a new computer, the old one still works
The cleanest flow has the app deactivate itself before the buyer retires the machine. Your app already stores the instance.id from activation. A menu item such as “Deactivate this computer” calls deactivate:
curl https://clavem.io/v1/licenses/deactivate \
-d license_key="YOUR-LICENSE-KEY" \
-d instance_id="47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"
A successful answer, from the API reference, contains "deactivated": true, and activation_usage shows the count after removal. The app then clears its stored key and token. On the new computer the buyer enters the key, the app calls activate, and the seat is used there.
Old computer License server New computer
| deactivate(key, instance_id) | |
|------------------------------->| |
| deactivated: true, usage 2->1 | |
|<-------------------------------| |
| | activate(key, name) |
| |<---------------------|
| | activated: true, |
| | new instance.id, |
| | token |
| |--------------------->|
If every seat is in use, the buyer has to deactivate first. If a seat is free, they can activate the new computer first and tidy up later.
When the last device is removed, an active license returns to inactive. Both are valid, so nothing breaks.
Case 2: the old computer is gone
A stolen laptop, a failed disk or a machine sold without a wipe cannot call deactivate. The seat stays used. Three ways to free it:
- The buyer, on the device page. Clavem’s page at
/licenses/manageneeds no account. The buyer pastes the key, sees every computer that uses it with the date it was last seen, and removes the ones they no longer use. Put the link in the error message your app shows when activation is refused. - You, in the dashboard. The license page lists its devices, each with a Remove button.
- You, by raising the limit.
PATCH /v1/admin/licenses/:idwithactivation_limitchanges the limit for that license. This is a blunt tool: it fixes today’s problem and leaves a stale seat behind. Prefer removing the stale device. Use the limit for a one-off, such as a buyer who really does need a fourth computer.
curl -X PATCH https://clavem.io/v1/admin/licenses/412 \
-H "Authorization: Bearer sk_clavem_…" \
-H "Content-Type: application/json" \
-d '{ "activation_limit": 4 }'
One more edge case: removing a device on the server does not switch that computer off at once. If its app is offline, it keeps running on its stored token until the token’s refresh deadline, at most 14 days after it was issued. When it next reaches the server, it learns the device was removed. If the concern is a stolen laptop and you need access to stop, disable the license and issue a replacement. Disabling takes effect on the next online check and on the token refresh.
What the old computer sees after a remote removal
When a removed device calls validate with its stored instance_id, it gets HTTP 404. This is the live response from the demo key with an instance_id that does not exist:
{
"valid": false,
"error": "instance_id not found.",
"license_key": { "id": 1, "status": "active", "activation_limit": 3, "activation_usage": 1, "…": "…" },
"instance": null,
"meta": { "…": "…" }
}
The key exists, but that instance does not. The body includes license_key, which tells it apart from the answer for an unknown key (license_key not found., which has no license_key object). A removed instance id is gone for good. Activating again gives a new one.
What should the app do? The quickstart’s flow clears the stored data and asks for the key again. You can be kinder. If the body has a license_key object, the key is good and only this computer was removed, so the app can try activate once with the key it stored:
- If
activatesucceeds, the buyer is back at work and never saw a message. - If it answers 400 with
This license key has reached the activation limit., show that sentence with a link to the device page.
Branch on the HTTP status and the presence of license_key, not on the error text. This function does it. I ran it against a stubbed License API, not production, with four scripted answers:
export async function recoverFromRemoval(saved, deviceName, store) {
const { status, body } = await call('validate', { license_key: saved.licenseKey, instance_id: saved.instanceId });
if (status === 200) return body.valid ? 'licensed' : 'invalid';
if (status !== 404) return 'no-answer'; // 400, 429, 5xx: fall back to the stored token
if (!body.license_key) { store.clear(); return 'ask-for-key'; } // key unknown
// The key is good, only this computer was removed. Try to take a seat again.
const act = await call('activate', { license_key: saved.licenseKey, instance_name: deviceName });
if (act.status === 200 && act.body.activated) {
store.save({ ...saved, instanceId: act.body.instance.id, token: act.body.token });
return 'licensed';
}
return act.status === 400 ? 'limit-reached' : 'invalid';
}
removed device, seat free -> licensed
removed device, limit full -> limit-reached
unknown key -> ask-for-key
rate limited -> no-answer
call is the small fetch wrapper from the quickstart. A caution: silently re-activating means a buyer whose device you removed on purpose, for example a stolen laptop, takes a seat again if one is free. If that matters, ask the buyer before re-activating, or do not auto-activate.
Edge cases that cost a support email
Deactivation fails halfway. The buyer clicks deactivate, the request reaches the server, and the connection drops before the answer. Next time, deactivate answers 404 with instance_id not found. Treat that as success: the seat is already free.
The app is offline when the buyer wants to deactivate. Do not block. Tell them to remove the computer on the device page when they are online.
Two computers, one person, both in use. A buyer with a limit of three can move freely among three computers. If they want a fourth, they need a different license or a higher limit on the one they have.
A virtual machine or a restored disk image. The machine may look new or old depending on the fingerprint, so a restore can use another seat. The buyer removes the stale one, as in case 2.
Fingerprints and transfers
If your app sends a fingerprint, activating again with one that is already active on the license returns the existing seat with its name updated. That helps with reinstalls on the same machine and does nothing for a new computer, which has a different fingerprint. It also has no effect after a removal, because a removed seat is gone and the fingerprint creates a fresh one. The mechanics are covered in machine fingerprinting pitfalls.
Case 3: the license goes to another person
A key works for whoever holds it. That is the whole difference from a named-user account. When a buyer asks “can I give this to my colleague?”, the technology has no opinion. You do.
The documented management API can change a license’s device limit, its expiry and whether it is disabled. It does not document a way to change the buyer’s name or email on an existing license. So you have three honest options:
| Policy | How it works | Trade-off |
|---|---|---|
| Not transferable | Your terms say a license is for the buyer only. | Simple. Some buyers will be unhappy, and a few will ask for exceptions. |
| Informal handover | The old owner deactivates their devices, passes the key on and tells you. | Cheap. The license record still names the old owner, and renewals go to them. |
| New license | You create a license for the new owner with POST /v1/admin/licenses, then disable the old one. |
Clean records and the new owner’s email on it. A new key, and you decide whether to charge. |
For a subscription license, a hand-made license has no Stripe subscription behind it, so Stripe renewals do not extend it. If the new owner should pay, they buy through Checkout and get a license from that purchase. Write the policy into your terms so the answer is the same each time.
Make the common case need no email
Three small things remove most transfer requests:
- An in-app “Deactivate this computer” action.
- The device page link in the activation-limit error message.
- A line on the order page and in the purchase email that says where to move a license.
A buyer replacing a laptop should reach the right button without writing to you.
Doing this with Clavem
The pieces are the three License API calls, the buyer’s device page, a dashboard that lists and removes devices, and PATCH /v1/admin/licenses/:id for the limit. Every activate and validate response says how many seats are used and how many are allowed. Clavem does not document changing the owner of a license, so ownership changes are a seller policy, as above. Details of the calls are in the API reference.
Questions
How do I move my license to a new computer?
Deactivate the license on the old computer, from the app or from the vendor's device page, then enter the key on the new computer. If the old computer is gone, remove it on the device page instead. That frees the seat.
What if I can no longer use the old computer?
Open the vendor's device page, paste the key, see the list of computers and remove the one you no longer have. The vendor can also remove it in their dashboard or raise the device limit.
Can I give my license to someone else?
That depends on the vendor's terms, not on the technology. A key works for whoever holds it, so a vendor who allows transfers usually asks the old owner to deactivate their devices and records the change of owner.