Guide de migration

Passer de Keygen à Paperkey en 10 minutes.

Vous exportez vos licenses depuis Keygen, vous transformez le JSON au format Paperkey, vous POSTez. Le SDK dans l'app livrée reste le même. Le dashboard, les webhooks, l'audit log se remplissent au premier reload.

~10 min pour moins de 500 licenses · ~1 h pour moins de 10k · scripté au-delà

Mapping des concepts

La plupart des concepts mappent un-pour-un. Trois noms diffèrent (Account, Policy, Token).

Keygen	Paperkey	Note
Account	Workspace (compte)	Isolation top-level. Un par société.
Product	Product	Même idée. Porte la config (cap, politique fingerprint).
Policy	Config produit	Inlinée dans le produit. Override par license sur la License.
License	License	Pareil. Formats de clé arbitraires acceptés à l'import.
Machine	Activation	Pareil. Fingerprint haché, slot du cap.
Token (license token)	Validation token	JWT émis par validate. Drop-in compatible.
Webhook	Webhook event	HMAC-SHA-256, signature hex, timeout 5s.
Entitlement	License metadata	Stocké en JSON sur la license. Lu par le SDK.

Keygen

Account

Paperkey

Workspace (compte)

Note

Isolation top-level. Un par société.
Keygen

Product

Paperkey

Product

Note

Même idée. Porte la config (cap, politique fingerprint).
Keygen

Policy

Paperkey

Config produit

Note

Inlinée dans le produit. Override par license sur la License.
Keygen

License

Paperkey

License

Note

Pareil. Formats de clé arbitraires acceptés à l'import.
Keygen

Machine

Paperkey

Activation

Note

Pareil. Fingerprint haché, slot du cap.
Keygen

Token (license token)

Paperkey

Validation token

Note

JWT émis par validate. Drop-in compatible.
Keygen

Webhook

Paperkey

Webhook event

Note

HMAC-SHA-256, signature hex, timeout 5s.
Keygen

Entitlement

Paperkey

License metadata

Note

Stocké en JSON sur la license. Lu par le SDK.

Quatre étapes

1. Exporter depuis Keygen

Utilisez l'API Keygen pour dumper toutes les licenses dans un fichier JSON. Remplacez <account-id> et <keygen-api-token> par vos valeurs.

step1.sh

curl -X GET 'https://api.keygen.sh/v1/accounts/<account-id>/licenses' \
  -H 'Authorization: Bearer <keygen-api-token>' \
  -H 'Accept: application/vnd.api+json' \
  > keygen-licenses.json

2. Transformer au format Paperkey

Un petit one-liner Node. Lit keygen-licenses.json, projette chaque license au format Paperkey, écrit paperkey-licenses.json. Sans dépendances externes.

step2.sh

node -e '
  const data = JSON.parse(require("fs").readFileSync("keygen-licenses.json", "utf8"));
  const out = data.data.map(l => ({
    key: l.attributes.key,
    customerEmail: l.relationships?.user?.data?.id ?? null,
    expiresAt: l.attributes.expiry,
    activationCap: l.attributes.maxMachines ?? 1,
    metadata: l.attributes.metadata ?? {},
  }));
  require("fs").writeFileSync(
    "paperkey-licenses.json",
    JSON.stringify(out, null, 2)
  );
'

3. Importer dans Paperkey

POSTez chaque license sur /v1/licenses. Bash + jq. L'endpoint est idempotent sur la clé, vous pouvez relancer en sécurité si une requête timeout.

step3.sh

jq -c '.[]' paperkey-licenses.json | while read -r row; do
  curl -X POST https://api.paperkey.dev/v1/licenses \
    -H "Authorization: Bearer pk_<your-api-key>" \
    -H 'Content-Type: application/json' \
    -d "$row"
done

4. Mettre à jour la config du SDK

Dans l'app livrée, pointez le SDK sur api.paperkey.dev avec la nouvelle clé publique de vérification. Le code d'appel SDK ne change pas. Les clients se réactivent tout seuls au prochain phone-home.

step4.ts

import { Paperkey } from '@paperkeyhq/sdk';

const pk = new Paperkey({
  apiUrl: 'https://api.paperkey.dev',
  productId: 'prod_<your-product-id>',
  publicKey: '<your-paperkey-public-verify-key>',
});

// Same call site as before. The SDK handles cache + offline grace.
const verdict = await pk.validate(licenseKey);

Limitations connues

Liste honnête. On vous le dit en amont pour que vous ne le découvriez pas en production.

Les fingerprints machine sont régénérés à la première activation sur Paperkey. Les slots machine Keygen existants sont traduits en « capacité disponible » sur la license, pas pré-attachés à des machines précises.
Les webhooks Keygen custom ne sont pas auto-rejoués. Re-subscribe dans le dashboard Paperkey avec les mêmes URLs cibles : on renvoie sur chaque state-change à partir de là.
Les entitlements complexes (flags par feature) arrivent en JSON metadata sur la license. Le SDK les expose via `license.metadata.<clé>`. Refactorez vos feature gates en conséquence.
L'historique analytics des licenses (charts, séries temporelles) ne migre pas. L'audit log Paperkey démarre au jour de l'import.

Besoin d'un coup de main ?

Si vous avez plus de 10k licenses, des entitlements complexes ou juste envie d'un regard sur la migration, écrivez avec la taille du compte Keygen et un créneau. Walkthrough de 30 minutes contre vos vraies données, gratuit.

Email hello@paperkey.dev