> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Claves de Licencia
> Genera y entrega claves de licencia únicas con límites de activación y vencimiento. Las claves de licencia son el tipo de derecho de Clave de Licencia. Se emiten automáticamente al realizar un pago, están ligadas al ciclo de vida de la suscripción y se revocan al cancelar o reembolsar.
Las claves de licencia son el tipo de derecho de Clave de Licencia. Crea un derecho de Clave de Licencia una vez con el límite de activación, vencimiento e instrucciones que desees, asígnalo a cualquier producto y Dodo Payments genera y entrega una clave por compra o asiento de suscripción, automáticamente.
## ¿Qué son las Claves de Licencia?
Las claves de licencia son tokens únicos que autorizan el acceso a tu producto. Son ideales para:
* **Licenciamiento de software**: Aplicaciones de escritorio, plugins y CLIs
* **Controles por asiento**: Limitar activaciones por usuario o dispositivo
* **Bienes digitales**: Restringir descargas, actualizaciones o características premium
Dentro de Dodo Payments, las claves de licencia se gestionan a través del sistema de [Derechos](/features/entitlements/introduction), lo que significa que el ciclo de vida de cada clave (creación, vencimiento, revocación, reactivación) está impulsado por los mismos eventos de pago y suscripción que tus otros entregables.
## Crear un Derecho de Clave de Licencia
Ve a **Derechos** en tu panel de Dodo Payments y haz clic en **+** para crear un nuevo derecho.
Selecciona **Clave de Licencia** como la integración. Configura cómo se comporta cada clave emitida:
* **Límite de Activaciones**: Activaciones concurrentes máximas por clave (por ejemplo, `1` para usuario único, `5` para licencias de equipo, dejar en blanco para ilimitado).
* **Duración**: Cuánto tiempo permanece válida la clave después de la emisión (por ejemplo, 30 días, 1 año). Para las claves emitidas por suscripción, dejar en blanco; las claves permanecen válidas mientras la suscripción esté activa.
* **Instrucciones de Activación**: Instrucciones para el cliente enviadas por correo electrónico con la clave. Ejemplos: `Paste the key in Settings → License` o `Run: mycli activate `.
Guardar. El derecho ahora está disponible para adjuntar a cualquier producto.
## Adjuntar a Productos
Abre un producto, expande **Configuración Avanzada → Derechos y Créditos**, y selecciona tu derecho de Clave de Licencia. Un solo producto puede entregar una clave de licencia junto con otros derechos (acceso a Discord, descargas de archivos, acceso a repositorio de GitHub, etc.) en la misma compra.
***
## Cómo se Emiten las Claves
La emisión de claves sigue el [ciclo de vida de concesión](/features/entitlements/introduction#how-grants-work) estándar:
| Evento | Comportamiento |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (único) | Genera una clave por cada `quantity` comprado. La caducidad de la clave respeta la duración del derecho. |
| `subscription.active` | Genera una clave por cada `quantity` de suscripción (asiento). La clave no tiene caducidad; la validez está ligada al estado de la suscripción. |
| `subscription.renewed` | Sin operación. Las claves existentes persisten. |
| `subscription.on_hold` | Desactiva las claves. Se reactivan cuando la suscripción sale de espera. |
| `subscription.cancelled` / `expired` | Desactiva las claves permanentemente. |
| `subscription.plan_changed` | Desactiva las claves antiguas; emite nuevas para el nuevo plan. |
| `refund.succeeded` (único) | Desactiva las claves. |
| Revocación manual vía API/panel | Desactiva las claves con `revocation_reason: manual`. No se reactivan automáticamente en la renovación de la suscripción. |
| Clave de licencia desactivada directamente | Revoca la concesión con `revocation_reason: license_key_disabled`. Rehabilitar la clave reactiva la concesión automáticamente. |
### Comportamiento de Cantidad
* **Productos de suscripción** emiten una clave por asiento (`subscriptions.quantity`).
* **Productos de una sola vez** emiten una clave por línea de artículo en el carrito (`product_cart.quantity`).
* **Concesiones manuales de API** emiten exactamente una clave.
## Activación, Validación, Desactivación
Los endpoints de API para activación/validación/desactivación son **públicos** y no requieren una clave API. Úsalos directamente desde software de escritorio, CLIs o clientes basados en navegador para verificar claves en tiempo de ejecución.
**Endpoints Públicos**: Los endpoints para activar, desactivar y validar licencias son públicos y no requieren una clave API. Llámalos directamente desde tus aplicaciones cliente sin exponer tus credenciales API.
### Activar una licencia
```typescript TypeScript theme={null} theme={null}
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);
```
```python Python theme={null} theme={null}
client.licenses.activate(
license_key="PRO-AAAA-BBBB-CCCC-DDDD",
name="Device Name",
)
```
```bash cURL theme={null} theme={null}
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"
}'
```
### Validar una licencia
```typescript TypeScript theme={null} theme={null}
const response = await client.licenses.validate({
license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});
console.log(response.valid);
```
```bash cURL theme={null} theme={null}
curl -X POST https://test.dodopayments.com/licenses/validate \
-H "Content-Type: application/json" \
-d '{ "license_key": "PRO-AAAA-BBBB-CCCC-DDDD" }'
```
### Desactivar una instancia de activación
```typescript theme={null} theme={null}
await client.licenses.deactivate({
license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
license_key_instance_id: 'instance_abc123',
});
```
***
## Gestionar Claves
Cuando un cliente compra un producto en modo manual, la concesión se crea en estado `pending` sin clave y un webhook [`entitlement_grant.created`](/developer-resources/webhooks/intents/entitlement-grant) se activa con `integration_type: "license_key"` e `status: "pending"`. Puedes reaccionar a ese webhook o consultar el endpoint [List Customer Grants](/api-reference/entitlements/list-customer-grants) con los filtros `integration_type` e `status`:
```typescript theme={null} theme={null}
const pending = await client.customers.listEntitlementGrants('customer_id', {
integration_type: 'license_key',
status: 'Pending',
});
```
```typescript theme={null} theme={null}
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);
}
```
## Importar Claves de Licencia Existentes vía API
¿Ya tienes claves de licencia en otro sistema? Usa la API de [Crear Clave de Licencia](/api-reference/licenses/create-license-key) para importarlas a Dodo Payments. Esto te permite migrar claves existentes sin interrumpir a tus clientes, quienes continúan activando, validando y desactivando con las mismas cadenas de clave sin reemisión.
Las claves de licencia creadas o actualizadas a través de la API no disparan notificaciones por correo electrónico a los clientes. Si necesitas notificar a los clientes sobre una clave importada, gestiona eso por separado en tu aplicación.
```typescript theme={null} theme={null}
const licenseKey = await client.licenseKeys.create({
customer_id: 'cus_abc123',
product_id: 'prod_456',
key: 'YOUR-EXISTING-LICENSE-KEY',
activations_limit: 5,
expires_at: '2026-12-31T23:59:59Z',
});
```
### Cómo difieren las claves importadas de las generadas automáticamente
| Campo | Clave generada automáticamente | Clave importada |
| ---------------------------------------------- | --------------------------------------------------- | ------------------------------------------------ |
| `source` | `"auto"` | `"import"` |
| `payment_id` | Configurado al pago de origen | `null` (sin transacción de Dodo Payments) |
| `subscription_id` | Configurado si la clave fue emitida vía suscripción | `null` a menos que esté vinculado explícitamente |
| Notificación por correo electrónico al cliente | Enviado al emitirse | No enviado, gestionar por separado |
Usa el campo `source` en las respuestas de `GET /license_keys` para distinguir el inventario migrado de las claves emitidas orgánicamente al conciliar o auditar.
¿Migrando de **Polar.sh** o **Lemon Squeezy**? El [`dodo-migrate` CLI](/migrate-to-dodo) automatiza importaciones masivas de productos, clientes, descuentos y claves de licencia en un solo comando y asigna automáticamente IDs externos a IDs de Dodo.
***
## Claves de Licencia en URL de Retorno
Cuando un cliente completa una compra de un producto con un derecho de Clave de Licencia, la clave generada se añade automáticamente a tu `return_url` como un parámetro de consulta. Esto te permite mostrar la clave inmediatamente en tu página de éxito sin hacer una llamada API adicional.
```text theme={null} theme={null}
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
```
Si la compra genera múltiples claves (cantidad > 1), se separan por comas:
```text theme={null} theme={null}
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com
```
Para suscripciones, se usa `subscription_id` en lugar de `payment_id`:
```text theme={null} theme={null}
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com
```
Analiza el parámetro `license_key` en tu página de retorno para mostrar la clave inmediatamente, mejorando la experiencia post-compra.
***
## Gestión de API
Activación, desactivación y validación son públicas; no se requiere clave API.
Crea o registra una instancia de activación para una clave de licencia.
Revoca una activación previa para liberar capacidad.
Verifica autenticidad, estado y restricciones antes de otorgar acceso.
Crea, lista, recupera y actualiza registros individuales de claves de licencia. Úsalos para importar claves existentes u obtener detalles de uso.
Crea una nueva clave de licencia o importa una existente.
```typescript theme={null} theme={null}
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);
}
```
Recupera una clave específica y sus metadatos.
Modifica caducidad, límites de activación o habilita/deshabilita una clave.
Gestiona el propio derecho de Clave de Licencia: su límite de activación, duración e instrucciones.
Crea un derecho de Clave de Licencia.
Actualiza la configuración del derecho.
Lista las claves emitidas para un derecho.
Revoca manualmente la clave de un cliente.
***
## Webhooks
La entrega y revocación de claves de licencia activan los cuatro [eventos webhook `entitlement_grant.*`](/developer-resources/webhooks/intents/entitlement-grant). La carga útil de concesión incluye un objeto `license_key` con la clave, caducidad, activaciones utilizadas y límite.
Los eventos heredados `license_key.*` (`license_key.created`) continúan activándose para el ciclo de vida del registro subyacente de la clave de licencia; vea la [página de carga útil de webhook de Clave de Licencia](/developer-resources/webhooks/intents/license-key).
Para nuevas integraciones, escuche `entitlement_grant.delivered` en lugar de `license_key.created`. El evento de derecho te dice que la entrega está completa en todas las integraciones en el producto, no solo en la clave de licencia.
***
## Claves de Licencia Heredadas
Los productos creados con la bandera antigua `license_key_enabled` han sido **automáticamente migrados** a un derecho de Clave de Licencia. La migración es transparente: las claves de los clientes existentes continúan funcionando sin cambios, los endpoints públicos `/licenses/activate`, `/licenses/validate`, `/licenses/deactivate` siguen funcionando, y los endpoints de la API `/license_keys/*` continúan leyendo y escribiendo en el mismo almacén de claves.
La sección de panel de **Claves de Licencia** independiente permanece disponible como una lista plana de cada clave emitida, útil para auditoría y búsqueda. La nueva configuración (cambiando límites de activación, duraciones o instrucciones) debe hacerse editando el derecho de Clave de Licencia migrado en **Derechos**.
***
## Mejores Prácticas
* **Mantén claros los límites de activación**: Elige valores predeterminados sensatos (1 para aplicaciones de un solo usuario, 3-5 para licencias de equipo) y documéntalos.
* **Proporciona instrucciones de activación precisas**: Los clientes las copian de su correo electrónico, así que las rutas y comandos exactos ahorran tickets de soporte.
* **Valida las claves en el servidor**: Para productos conectados a la red, valida a través de `/licenses/validate` en lugar de almacenar en caché la activación localmente.
* **Usa webhooks para revocación**: Escucha `entitlement_grant.revoked` para desactivar características en la aplicación inmediatamente cuando un cliente cancela o solicita un reembolso.
* **Prueba con suscripciones y adquisiciones únicas**: El comportamiento de las claves de licencia difiere sutilmente entre ambos, así que prueba ambos antes de lanzar.
Parse el parámetro `license_key` en su página de retorno para mostrar la clave inmediatamente, mejorando la experiencia post-compra.
***
## Gestión de API
Activación, desactivación y validación son públicas; no se requiere clave de API.
Crear o registrar una instancia de activación para una clave de licencia.
Revocar una activación anterior para liberar capacidad.
Verificar autenticidad, estado y restricciones antes de otorgar acceso.
Crear, listar, recuperar y actualizar registros individuales de claves de licencia. Úselos para importar claves existentes u obtener detalles de uso.
Crear una nueva clave de licencia o importar una existente.
Navegar por todas las claves con detalles de estado y uso.
Recuperar una clave específica y su metadata.
Modificar caducidad, límites de activación o habilitar/deshabilitar una clave.
Gestionar el derecho de la Clave de Licencia en sí misma: su límite de activación, duración e instrucciones.
Crear un derecho de Clave de Licencia.
Actualizar la configuración del derecho.
Listar las claves emitidas para un derecho.
Revocar manualmente la clave de un cliente.
***
## Webhooks
La entrega y revocación de claves de licencia activan los cuatro [eventos webhook `entitlement_grant.*`](/developer-resources/webhooks/intents/entitlement-grant). La carga útil de la concesión incluye un objeto `license_key` con la clave, caducidad, activaciones usadas y límite.
Los eventos heredados `license_key.*` (`license_key.created`) continúan activándose durante el ciclo de vida del registro de la clave de licencia; vea la [página de carga útil del webhook de Clave de Licencia](/developer-resources/webhooks/intents/license-key).
Para nuevas integraciones, escuche `entitlement_grant.delivered` en lugar de `license_key.created`. El evento de derecho le indica que la entrega está completa en todas las integraciones del producto, no solo en la clave de licencia.
***
## Claves de Licencia Heredadas
Los productos creados con la bandera `license_key_enabled` anterior han sido **migrados automáticamente** a un derecho de Clave de Licencia. La migración es transparente: las claves de los clientes existentes continúan funcionando sin cambios, los endpoints públicos `/licenses/activate`, `/licenses/validate`, `/licenses/deactivate` continúan funcionando, y los endpoints de API `/license_keys/*` continúan leyendo y escribiendo en el mismo almacén de claves.
La sección de panel independiente **Claves de Licencia** sigue estando disponible como una lista plana de todas las claves emitidas, útil para auditoría y búsqueda. La nueva configuración (cambiar límites de activación, duraciones o instrucciones) debe realizarse editando el derecho de Clave de Licencia migrado en **Derechos**.
***
## Mejores Prácticas
* **Mantenga claros los límites de activación**: Elija valores predeterminados sensatos (1 para aplicaciones de un solo usuario, 3–5 para licencias de equipo) y documéntelos.
* **Proporcione instrucciones precisas de activación**: Los clientes las copian de su correo electrónico, por lo que las rutas y comandos exactos ahorran tickets de soporte.
* **Valide claves del lado del servidor**: Para productos conectados a la red, valide a través de `/licenses/validate` en lugar de almacenar en caché la activación localmente.
* **Use webhooks para revocación**: Escuche `entitlement_grant.revoked` para deshabilitar características en la aplicación inmediatamente cuando un cliente cancela o recibe un reembolso.
* **Prueba con suscripciones y únicas**: El comportamiento de las claves de licencia difiere sutilmente entre las dos, así que pruebe ambas antes de salir en vivo.
***
## Cómo se Emiten las Claves
La emisión de claves sigue el [ciclo de vida de concesión](/features/entitlements/introduction#how-grants-work) estándar:
| Evento | Comportamiento |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (único) | Genera una clave por cada `quantity` comprado. La caducidad de la clave respeta la duración del derecho. |
| `subscription.active` | Genera una clave por cada `quantity` de suscripción (asiento). La clave no tiene caducidad; la validez está ligada al estado de la suscripción. |
| `subscription.renewed` | Sin operación. Las claves existentes persisten. |
| `subscription.on_hold` | Desactiva las claves. Se reactivan cuando la suscripción sale de espera. |
| `subscription.cancelled` / `expired` | Desactiva las claves permanentemente. |
| `subscription.plan_changed` | Desactiva las claves antiguas; emite nuevas para el nuevo plan. |
| `refund.succeeded` (único) | Desactiva las claves. |
| Revocación manual vía API/panel | Desactiva las claves con `revocation_reason: manual`. No se reactivan automáticamente en la renovación de la suscripción. |
| Clave de licencia desactivada directamente | Revoca la concesión con `revocation_reason: license_key_disabled`. Rehabilitar la clave reactiva la concesión automáticamente. |
### Comportamiento de Cantidad
* **Productos de suscripción** emiten una clave por asiento (`subscriptions.quantity`).
* **Productos de una sola vez** emiten una clave por línea de artículo en el carrito (`product_cart.quantity`).
* **Concesiones manuales de API** emiten exactamente una clave.
## Activación, Validación, Desactivación
Los endpoints de API para activación/validación/desactivación son **públicos** y no requieren una clave API. Úsalos directamente desde software de escritorio, CLIs o clientes basados en navegador para verificar claves en tiempo de ejecución.