Why a key gets lost, and why it matters
A license key arrives once, in an email, on the day of purchase. The buyer uses it, closes the email and returns eighteen months later with a new laptop. The email is in a folder they cannot find, or went to an address they no longer read.
Two goals pull against each other. You want recovery to be fast, because an angry customer is a refund request. And you want recovery to be safe, because in a system where the key is the credential, a recovery flow that is too generous is a way to take someone else’s key. In Clavem’s License API, nothing but the key is needed to activate or validate. A recovery flow is therefore a way of handing out credentials, and it deserves the same care as a password reset.
The layers of recovery, from cheapest to most work
| Layer | Who does it | Fits |
|---|---|---|
| The order page link in the purchase email | The buyer | Everyone who still has the email |
| The key shown in the app’s license screen | Your app | Anyone who has activated the app |
| Resend from the dashboard | You, on request | One-off support requests |
| An “email me my key” form on your site | The buyer, through your server | Enough requests to justify building it |
| Support looks it up by email in the dashboard | You | Everything else |
Start at the top. Most lost keys are prevented by the second row. After activation, show the license in the app, masked to the first and last five characters, together with a link to the order page and the device page. Buyers who can see “Licensed to ada@example.com, key S1GNE…H5RB8” do not need to hunt for the email.
Keys that survive being read aloud
Some recovery requests arrive as a screenshot, a phone call or a photo of a screen. A key format that tolerates misreading saves a round trip. Clavem’s generated keys use Crockford base32, which leaves out the letters I, L, O and U, and the License API forgives the usual confusions: I and L read as 1, O as 0 and U as V, and capitals do not matter. A buyer who types S1GNE-TDEMO-... for S1GNE-TDEM0-... still activates. Imported keys, such as Lemon Squeezy UUIDs, match as written, lower-cased, so those do not get the same forgiveness.
If your own app also validates the format of what the buyer typed, do not be stricter than the server. Trim whitespace, and let the server decide.
What Clavem gives each buyer
For every Stripe purchase Clavem creates an order, a private order page at /o/<token>, and an email with the keys and the order link. The order page shows the key with a copy button, the downloads and your activation instructions. The link is an unguessable token, so treat it like the key: whoever holds it can see the key.
Licenses you create by hand, in the dashboard or with the management API, also get an order and an order page. In the dashboard, a license that has an order page shows two buttons on its detail page: Open order page and Email the key again. The second sends the buyer the email, so you do not copy the key into a chat.
Licenses imported from another system, such as Lemon Squeezy, have no order and so no order page. Those buyers can still manage devices at /licenses/manage if they have the key. For a lost imported key, you look it up and send it to them.
Look up by email, from your server
When a buyer writes in, find the license by the address they bought with. In the dashboard, search by email. From your own code, use the management API. It needs your secret key, so it can only run on your server:
curl "https://clavem.io/v1/admin/licenses?email=ada%40example.com&limit=20" \
-H "Authorization: Bearer sk_clavem_…"
The email filter is an exact match on the buyer’s address. The response is a list wrapped in data, newest first, with a next_before cursor when there are more:
{
"data": [
{
"id": 412,
"key": "7QX2M-9WZ2P-H5RB8-K4TEV-0A1CD",
"status": "inactive",
"product_name": "Inkwell",
"customer_email": "ada@example.com",
"test_mode": false
}
],
"next_before": null
}
This is the shape from the API reference with some fields left out. You can also filter by key and product_id. There is no filter by name, which is deliberate in a sense: see the list of what not to build below.
A safe “email me my key” form
If you get enough requests to build self-service, the rules are short:
- Never show the key on the page. Send it to the address on file. The page says only “If that address has a license, we have emailed it.”
- Give the same answer in every case. If the page confirms “no license for this address”, it tells a stranger which addresses are customers.
- Rate limit by IP address and by email address. Otherwise your form is a mail cannon aimed at your customers.
- Run the lookup on your server. The management key must never be in a browser or in your app.
- Skip test-mode licenses.
test_modemarks Stripe test purchases.
I wrote a small handler and ran it with a stubbed fetch and mail function. It does not call the live API. It returned the identical message for a known and an unknown address, sent one email to the known address, and after the third attempt for the same address it sent nothing more.
const API = 'https://clavem.io/v1/admin';
const GENERIC = { ok: true, message: 'If that address has a license, we have emailed it.' };
export async function recoverKeys(email, ip, { sendEmail, allow }) {
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return GENERIC;
if (!allow('ip:' + ip) || !allow('email:' + email.toLowerCase())) return GENERIC;
const res = await fetch(`${API}/licenses?email=${encodeURIComponent(email)}&limit=20`, {
headers: { Authorization: `Bearer ${process.env.CLAVEM_API_KEY}` },
});
if (!res.ok) return GENERIC;
const { data } = await res.json();
const keys = data.filter((l) => !l.test_mode);
if (keys.length > 0) {
await sendEmail(email, keys.map((l) => `${l.product_name}: ${l.key} (${l.status})`).join('\n'));
}
return GENERIC; // the same answer whether or not anything was found
}
One detail remains. The response time differs slightly when a license exists, because the handler makes an extra call and sends a mail. If that matters for your product, put the work on a queue and return at once.
What not to build
Lookup by name. Names are not unique, they are easy to learn, and there is no name filter in the management API.
Lookup by card digits, postcode or other “verification” details. You do not hold them, and anyone who knows them can claim to be the buyer.
A page that lists the licenses for an email address. It tells anyone who types an address which keys exist.
Keys in public support channels. Keys are credentials. Use the order page link or an email to the address on file, and avoid pasting keys into public issue trackers or chat rooms.
When the address is wrong
Most failures are not a security problem. They are a buyer who bought with an address they forgot. Ask them for each address they might have used: a work address, an old provider, a forwarding alias, or an alias such as Apple’s hide-my-email. Search for each. If the buyer remembers roughly when they bought, you can also look through the payments in your own Stripe records and read the email on the one that matches. That is a lookup in your own data, not something the buyer has to prove.
If the email on the purchase is one the buyer cannot read any more, that is an identity decision for you, not for software. Make it consistently, and write the rule down.
A support reply to copy
Hi, thanks for writing. I found one license for this address and have emailed the key and the order page link to it. Check your spam folder if it is not there in a few minutes. If you no longer have access to that address, tell me the address you remember and when you bought, and I will search for it. Once you have the key, paste it into the app under License. If the app says it has reached its device limit, open clavem.io/licenses/manage, paste the key and remove computers you no longer use.
Adapt the last sentence to your own store. The device page also shows your store name and support email.
Doing this with Clavem
The pieces Clavem provides: the order page, the email with keys, Email the key again in the dashboard, search by email and key, the management API lookup shown above, and the device page. What it does not provide is a public “email me my key” form: you build that on your own server if you want it, as above. The API reference has every field of the license object, and releases and downloads explains why imported licenses have no order page.
Questions
How do I recover a lost license key?
Look up the license by the buyer's email address in your licensing dashboard or API, then send the key, or the order page link, to the address on the purchase. Do not send it to a different address without a way to confirm who is asking.
Should a recovery form show the license key on screen?
No. Anyone who can guess or learn an email address could read the key. Send it by email to that address, and show the same confirmation message whether or not a license exists.
What if the buyer used a different email address?
This is the most common failure. Ask which addresses they might have used, including work addresses, forwarding addresses and Apple's hide-my-email aliases, and search for each. Do not hand out keys on the strength of a name alone.