License Keys

​

What are License Keys?

• Software licensing: Desktop apps, plugins, and CLIs
• Per-seat controls: Limit activations per user or device
• Digital goods: Gate downloads, updates, or premium features

​

Create a License Key Entitlement

1

Open Entitlements

Go to Entitlements in your Dodo Payments dashboard and click + to create a new entitlement.

2

Choose License Key

Select License Key as the integration. Configure how each issued key behaves:

• Activations Limit: Maximum concurrent activations per key (e.g., 1 for single-user, 5 for team licenses, leave blank for unlimited).
• Duration: How long the key stays valid after issuance (e.g., 30 days, 1 year). For subscription-issued keys, leave blank; keys remain valid as long as the subscription is active.
• Activation Instructions: Customer-facing instructions emailed with the key. Examples: Paste the key in Settings → License or Run: mycli activate <key>.

3

Save the entitlement

Save. The entitlement is now available to attach to any product.

​

Attach to Products

​

How Keys Are Issued

​

Quantity behavior

• Subscription products issue one key per seat (subscriptions.quantity).
• One-time products issue one key per cart line item (product_cart.quantity).
• Manual API grants issue exactly one key.

​

Mode de réalisation

• auto (par défaut) : Dodo Payments génère et envoie automatiquement la clé par e-mail lors du paiement ou de la souscription. Il s’agit du comportement décrit ci-dessus, qui s’applique lorsque fulfillment_mode est omis.
• manual : L’achat crée un grant Pending sans clé, et vous fournissez vous-même chaque valeur de clé. Consultez la section Fulfillment manuel ci-dessous.

​

Réalisation manuelle

​

Quand l’utiliser

• Utilisation de vos propres clés : La clé est générée par votre application, un produit de bureau ou votre propre serveur de licences.
• Fournisseurs tiers : Vous revendez des clés émises par un fournisseur en amont (une clé de jeu, une crédentielle API, une plateforme partenaire).
• Inventaire fini : Vous distribuez des codes à partir d’un pool pré-allocé et souhaitez les attribuer un par un.
• Examen humain : Vous souhaitez vérifier un achat avant de libérer l’accès.

​

Activer la réalisation manuelle

const entitlement = await client.entitlements.create({
  name: 'Pro License (Manual)',
  integration_type: 'license_key',
  integration_config: {
    fulfillment_mode: 'manual',
    activations_limit: 5,
    duration_count: 1,
    duration_interval: 'Year',
  },
});

curl -X POST https://test.dodopayments.com/entitlements \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro License (Manual)",
    "integration_type": "license_key",
    "integration_config": {
      "fulfillment_mode": "manual",
      "activations_limit": 5,
      "duration_count": 1,
      "duration_interval": "Year"
    }
  }'

​

Trouver les subventions en attente de réalisation

const pending = await client.customers.listEntitlementGrants('customer_id', {
  integration_type: 'license_key',
  status: 'Pending',
});

​

Livrer la clé

curl -X POST https://test.dodopayments.com/grants/grant_8VbC6JDZ/license-key \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "activations_limit": 5,
    "expires_at": "2027-05-01T00:00:00Z"
  }'

​

Activation, Validation, Désactivation

​

Activer une licence

import DodoPayments from 'dodopayments';

// No API key needed for public license endpoints
const client = new DodoPayments();

const response = await client.licenses.activate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  name: 'Device Name',
});

console.log(response.id);

client.licenses.activate(
    license_key="PRO-AAAA-BBBB-CCCC-DDDD",
    name="Device Name",
)

curl -X POST https://test.dodopayments.com/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "name": "Device Name"
  }'

​

Valider une licence

const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

curl -X POST https://test.dodopayments.com/licenses/validate \
  -H "Content-Type: application/json" \
  -d '{ "license_key": "PRO-AAAA-BBBB-CCCC-DDDD" }'

​

Désactiver une instance d’activation

await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'instance_abc123',
});

​

Gérer les clés

const grants = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'Delivered',
});

for (const grant of grants.items) {
  console.log(grant.license_key.key, grant.license_key.activations_used);
}

​

Importer des clés de licence existantes via l’API

const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​

Comment les clés diffèrent selon la source

​

Clés de licence dans l’URL de retour

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com

https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com

​

Gestion API

​

Webhooks

​

Clés de licence héritées

​

Bonnes pratiques

• Définissez clairement les limites d’activation : choisissez des valeurs par défaut adaptées (1 pour les applications mono-utilisateur, 3 à 5 pour les licences d’équipe) et documentez-les.
• Fournissez des instructions d’activation précises : les clients les copient depuis leur e-mail ; des chemins et des commandes exacts réduisent les demandes d’assistance.
• Validez les clés côté serveur : pour les produits connectés au réseau, validez-les via /licenses/validate plutôt que de mettre l’activation en cache localement.
• Utilisez les webhooks pour la révocation : écoutez entitlement_grant.revoked afin de désactiver immédiatement les fonctionnalités de l’application lorsqu’un client annule ou demande un remboursement.
• Testez avec des abonnements et des achats ponctuels : le comportement des clés de licence diffère subtilement entre ces deux cas ; testez-les donc tous les deux avant la mise en production.