> ## 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.

# Chiavi di Licenza

> Genera e consegna chiavi di licenza uniche con limiti di attivazione e scadenza. Le chiavi di licenza sono il tipo di diritto License Key. Vengono emesse automaticamente al pagamento, legate al ciclo di vita dell'abbonamento e revocate in caso di cancellazione o rimborso.

<Frame>
  <iframe className="w-full aspect-video rounded-md" src="https://www.youtube.com/embed/BNuLTXok8dQ" title="License Keys | Dodo Payments" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

<Info>
  Le chiavi di licenza sono il tipo di diritto License Key. Crea un diritto License Key una volta con il limite di attivazione, la scadenza e le istruzioni che desideri, allegalo a qualsiasi prodotto e Dodo Payments genera e consegna automaticamente una chiave per acquisto o posto in abbonamento.
</Info>

## Cosa sono le chiavi di licenza?

Le chiavi di licenza sono token unici che autorizzano l'accesso al tuo prodotto. Sono ideali per:

* **Licenze software**: App desktop, plugin e CLI
* **Controlli per utente**: Limita le attivazioni per utente o dispositivo
* **Beni digitali**: Regola download, aggiornamenti o funzionalità premium

All'interno di Dodo Payments, le chiavi di licenza sono gestite attraverso il sistema di [Diritti](/features/entitlements/introduction), il che significa che il ciclo di vita di ogni chiave (creazione, scadenza, revoca, ri-concessione) è guidato dagli stessi eventi di pagamento e abbonamento come gli altri tuoi deliverable.

## Crea un diritto di chiave di licenza

<Steps>
  <Step title="Open Entitlements">
    Vai su **Diritti** nel tuo dashboard Dodo Payments e fai clic su **+** per creare un nuovo diritto.
  </Step>

  <Step title="Choose License Key">
    Seleziona **License Key** come integrazione. Configura come si comporta ogni chiave emessa:

    * **Limite di Attivazioni**: Massimo di attivazioni simultanee per chiave (es., `1` per singolo utente, `5` per licenze di squadra, lascia vuoto per illimitate).
    * **Durata**: Quanto tempo la chiave rimane valida dopo l'emissione (es., 30 giorni, 1 anno). Per le chiavi emesse per abbonamento, lascia vuoto; le chiavi rimangono valide finché l'abbonamento è attivo.
    * **Istruzioni di Attivazione**: Istruzioni per i clienti inviate via email con la chiave. Esempi: `Paste the key in Settings → License` o `Run: mycli activate <key>`.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/sZYZEc6Biy3IrQNZ/images/entitlements/license-keys/create.png?fit=max&auto=format&n=sZYZEc6Biy3IrQNZ&q=85&s=65f24596e834387d0c35278ef92d14ea" alt="Modulo di diritto License Key con limite di attivazione, durata e istruzioni" style={{ maxHeight: '500px', width: 'auto' }} width="2840" height="1614" data-path="images/entitlements/license-keys/create.png" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Salva. Il diritto è ora disponibile per essere allegato a qualsiasi prodotto.
  </Step>
</Steps>

## Allegare ai Prodotti

Apri un prodotto, espandi **Impostazioni Avanzate → Diritti & Crediti**, e seleziona il tuo diritto License Key. Un singolo prodotto può consegnare una chiave di licenza insieme ad altri diritti (accesso a Discord, download di file, accesso a repository GitHub, ecc.) nello stesso acquisto.

<Frame caption="Selecting the License Key entitlement in the product entitlements panel.">
  <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/attach-to-product.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=965ad78262791fa8dbb712b4fdf89538" alt="Pannello diritti del prodotto con License Key selezionato" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1197" data-path="images/entitlements/attach-to-product.png" />
</Frame>

***

## Come vengono emesse le chiavi

L'emissione delle chiavi segue il [ciclo di vita della concessione](/features/entitlements/introduction#how-grants-work) standard:

| Evento                                      | Comportamento                                                                                                                      |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (una tantum)            | Genera una chiave per `quantity` acquistata. La scadenza della chiave rispetta la durata del diritto.                              |
| `subscription.active`                       | Genera una chiave per abbonamento `quantity` (posto). La chiave non ha scadenza; la validità è legata allo stato dell'abbonamento. |
| `subscription.renewed`                      | No-op. Le chiavi esistenti persistono.                                                                                             |
| `subscription.on_hold`                      | Disabilita le chiavi. Si riattivano quando l'abbonamento esce dalla sospensione.                                                   |
| `subscription.cancelled` / `expired`        | Disabilita permanentemente le chiavi.                                                                                              |
| `subscription.plan_changed`                 | Disabilita le vecchie chiavi; emette nuove per il nuovo piano.                                                                     |
| `refund.succeeded` (una tantum)             | Disabilita le chiavi.                                                                                                              |
| Revoca manuale via API/dashboard            | Disabilita le chiavi con `revocation_reason: manual`. Queste non sono ri-concesse automaticamente al rinnovo dell'abbonamento.     |
| Chiave di licenza disabilitata direttamente | Revoca il diritto con `revocation_reason: license_key_disabled`. Riabilitazione della chiave riattiva il diritto automaticamente.  |

### Comportamento della quantità

* **Prodotti in abbonamento** rilasciano una chiave per posto (`subscriptions.quantity`).
* **Prodotti una tantum** rilasciano una chiave per articolo nella riga del carrello (`product_cart.quantity`).
* **Concessioni API manuali** rilasciano esattamente una chiave.

## Attivazione, Validazione, Disattivazione

Gli endpoint API di attivazione/validazione/disattivazione sono **pubblici** e non richiedono una chiave API. Usali direttamente da software desktop, CLI o client basati su browser per verificare le chiavi durante l'esecuzione.

<Info>
  **Endpoint Pubblici**: Gli endpoint di attivazione, disattivazione e validazione delle licenze sono pubblici e non richiedono una chiave API. Chiamali direttamente dalle tue applicazioni client senza esporre le tue credenziali API.
</Info>

### Attivare una licenza

<CodeGroup>
  ```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"
    }'
  ```
</CodeGroup>

### Validare una licenza

<CodeGroup>
  ```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" }'
  ```
</CodeGroup>

### Disattivare un'istanza di attivazione

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

***

## Gestire le Chiavi

Quando un cliente acquista un prodotto in modalità manuale, la concessione viene creata nello stato `pending` senza chiave e un [`entitlement_grant.created`](/developer-resources/webhooks/intents/entitlement-grant) webhook viene attivato con `integration_type: "license_key"` e `status: "pending"`. Puoi reagire a quel webhook o interrogare l'endpoint [List Customer Grants](/api-reference/entitlements/list-customer-grants) con i filtri `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);
}
```

## Importare Chiavi di Licenza Esistenti tramite API

Hai già chiavi di licenza in un altro sistema? Usa l'API [Crea License Key](/api-reference/licenses/create-license-key) per importarle in Dodo Payments. Questo ti permette di migrare le chiavi esistenti senza interrompere i tuoi clienti — continuano ad attivare, validare, e disattivare contro le stesse stringhe di chiavi senza ri-emissione.

<Warning>
  Le chiavi di licenza create o aggiornate tramite l'API non attivano notifiche email ai clienti. Se hai bisogno di notificare i clienti riguardo una chiave importata, gestiscilo separatamente nella tua applicazione.
</Warning>

```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',
});
```

### Come le chiavi importate differiscono dalle chiavi auto-generate

| Campo                     | Chiave auto-generata                                         | Chiave importata                                   |
| ------------------------- | ------------------------------------------------------------ | -------------------------------------------------- |
| `source`                  | `"auto"`                                                     | `"import"`                                         |
| `payment_id`              | Impostato sul pagamento originante                           | `null` (nessuna transazione Dodo Payments)         |
| `subscription_id`         | Impostato se la chiave è stata emessa tramite un abbonamento | `null` a meno che non sia esplicitamente collegato |
| Notifica email al cliente | Inviata all'emissione                                        | Non inviata — gestire separatamente                |

Usa il campo `source` nelle risposte `GET /license_keys` per distinguere l'inventario migrato dalle chiavi emesse organicamente quando si concilia o si effettua un controllo.

<Tip>
  Migrazione da **Polar.sh** o **Lemon Squeezy**? La [CLI `dodo-migrate`](/migrate-to-dodo) automatizza le importazioni in massa di prodotti, clienti, sconti e chiavi di licenza in un unico comando e mappa automaticamente gli ID esterni agli ID Dodo.
</Tip>

***

## Chiavi di Licenza nell'URL di Ritorno

Quando un cliente completa un acquisto per un prodotto con un diritto di License Key, la chiave generata viene automaticamente aggiunta alla tua `return_url` come un parametro di query. Questo ti permette di visualizzare immediatamente la chiave sulla tua pagina di successo senza effettuare una chiamata API aggiuntiva.

```text theme={null} theme={null}
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
```

Se l'acquisto genera più chiavi (quantità > 1), sono separate da virgole:

```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
```

Per gli abbonamenti, viene utilizzato `subscription_id` invece di `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
```

<Tip>
  Analizza il parametro `license_key` sulla tua pagina di ritorno per mostrare immediatamente la chiave, migliorando l'esperienza post-acquisto.
</Tip>

***

## Gestione API

<AccordionGroup>
  <Accordion title="Lifecycle Operations (Public Endpoints)">
    Attivazione, disattivazione e validazione sono pubblici; non è richiesta una chiave API.

    <CardGroup cols={3}>
      <Card title="Activate License" icon="code" href="/api-reference/licenses/activate-license">
        Crea o registra un'istanza di attivazione per una chiave di licenza.
      </Card>

      <Card title="Deactivate License" icon="code" href="/api-reference/licenses/deactivate-license">
        Revoca un'attivazione precedente per liberare capacità.
      </Card>

      <Card title="Validate License" icon="code" href="/api-reference/licenses/validate-license">
        Controlla l'autenticità, lo stato e i vincoli prima di concedere l'accesso.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="License Key Management">
    Crea, elenca, recupera e aggiorna i record individuali delle chiavi di licenza. Usa questi per importare chiavi esistenti o recuperare i dettagli di utilizzo.

    <CardGroup cols={2}>
      <Card title="Create License Key" icon="code" href="/api-reference/licenses/create-license-key">
        Crea una nuova chiave di licenza o importa una esistente.
      </Card>

      ```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);
      }
      ```

      <Card title="Get License Key" icon="code" href="/api-reference/licenses/get-license-key">
        Recupera una chiave specifica e i suoi metadati.
      </Card>

      <Card title="Update License Key" icon="code" href="/api-reference/licenses/update-license-key">
        Modifica la scadenza, i limiti di attivazione o abilita/disabilita una chiave.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Entitlement Management">
    Gestire il diritto License Key stesso: il suo limite di attivazione, durata e istruzioni.

    <CardGroup cols={2}>
      <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
        Crea un diritto License Key.
      </Card>

      <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
        Aggiorna la configurazione del diritto.
      </Card>

      <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
        Elenca le chiavi emesse per un diritto.
      </Card>

      <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
        Revoca manualmente la chiave di un cliente.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

## Webhooks

La consegna e la revoca delle chiavi di licenza attivano i quattro [eventi webhook `entitlement_grant.*`](/developer-resources/webhooks/intents/entitlement-grant). Il payload della concessione include un oggetto `license_key` popolato con la chiave, la scadenza, le attivazioni usate e il limite.

Gli eventi legacy `license_key.*` (`license_key.created`) continuano a essere attivati per il ciclo di vita dei record delle chiavi di licenza sottostanti; vedi la [pagina del payload webhook delle chiavi di licenza](/developer-resources/webhooks/intents/license-key).

<Tip>
  Per nuove integrazioni, ascolta `entitlement_grant.delivered` piuttosto che `license_key.created`. L'evento di diritto ti dice che la consegna è completa su tutte le integrazioni del prodotto, non solo chiave di licenza.
</Tip>

***

## Chiavi di Licenza Legacy

<Note>
  I prodotti creati con la vecchia flag `license_key_enabled` sono stati **automaticamente migrati** a un diritto License Key. La migrazione è trasparente: le chiavi esistenti dei clienti continuano a funzionare inalterate, gli endpoint pubblici `/licenses/activate`, `/licenses/validate`, `/licenses/deactivate` continuano a funzionare, e gli endpoint API `/license_keys/*` continuano a leggere e scrivere nello stesso archivio chiavi.

  La sezione autonoma **License Keys** del dashboard rimane disponibile come un elenco piatto di ogni chiave emessa, utile per controllo e ricerca. La nuova configurazione (cambiando i limiti di attivazione, le durate o le istruzioni) deve essere fatta modificando il diritto License Key migrato sotto **Diritti**.
</Note>

***

## Migliori Pratiche

* **Mantieni chiari i limiti di attivazione**: Scegli impostazioni predefinite sensate (1 per app a utente singolo, 3–5 per licenze di team) e documentali.
* **Fornisci istruzioni precise di attivazione**: I clienti incollano queste dalla loro email, quindi percorsi e comandi esatti riducono i ticket di supporto.
* **Valida le chiavi lato server**: Per prodotti connessi alla rete, valida tramite `/licenses/validate` piuttosto che memorizzare localmente l'attivazione in cache.
* **Usa webhooks per la revoca**: Ascolta `entitlement_grant.revoked` per disabilitare immediatamente le funzionalità in-app quando un cliente annulla o rimborsa.
* **Testa con abbonamenti e una tantum**: Il comportamento delle chiavi di licenza differisce leggermente tra i due, quindi testa entrambi prima di andare in produzione.

<Tip>
  Analizza il parametro `license_key` nella tua pagina di ritorno per mostrare immediatamente la chiave, migliorando l'esperienza post-acquisto.
</Tip>

***

## Gestione API

<AccordionGroup>
  <Accordion title="Lifecycle Operations (Public Endpoints)">
    Attivazione, disattivazione e convalida sono pubbliche; non è richiesta una chiave API.

    <CardGroup cols={3}>
      <Card title="Activate License" icon="code" href="/api-reference/licenses/activate-license">
        Crea o registra un'istanza di attivazione per una chiave di licenza.
      </Card>

      <Card title="Deactivate License" icon="code" href="/api-reference/licenses/deactivate-license">
        Revoca un'attivazione precedente per liberare capacità.
      </Card>

      <Card title="Validate License" icon="code" href="/api-reference/licenses/validate-license">
        Verifica autenticità, stato e vincoli prima di concedere l'accesso.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="License Key Management">
    Crea, elenca, recupera e aggiorna i record di singole chiavi di licenza. Utilizzali per importare chiavi esistenti o ottenere dettagli sull'uso.

    <CardGroup cols={2}>
      <Card title="Create License Key" icon="code" href="/api-reference/licenses/create-license-key">
        Crea una nuova chiave di licenza o importa una esistente.
      </Card>

      <Card title="List License Keys" icon="code" href="/api-reference/licenses/list-license-keys">
        Sfoglia tutte le chiavi con dettagli di stato e utilizzo.
      </Card>

      <Card title="Get License Key" icon="code" href="/api-reference/licenses/get-license-key">
        Recupera una chiave specifica e i suoi metadati.
      </Card>

      <Card title="Update License Key" icon="code" href="/api-reference/licenses/update-license-key">
        Modifica scadenza, limiti di attivazione o abilita/disabilita una chiave.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Entitlement Management">
    Gestisci lo stesso diritto della chiave di licenza: il suo limite di attivazione, durata e istruzioni.

    <CardGroup cols={2}>
      <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
        Crea un diritto di chiave di licenza.
      </Card>

      <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
        Aggiorna la configurazione del diritto.
      </Card>

      <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
        Elenca le chiavi emesse per un diritto.
      </Card>

      <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
        Revoca manualmente la chiave di un cliente.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

## Webhook

La consegna e la revoca della chiave di licenza attivano i quattro eventi [`entitlement_grant.*` webhook](/developer-resources/webhooks/intents/entitlement-grant). Il payload del grant include un oggetto `license_key` popolato con la chiave, scadenza, attivazioni usate e limite.

Gli eventi legacy `license_key.*` (`license_key.created`) continuano ad attivarsi per il ciclo di vita del record della chiave di licenza; vedi la [pagina del payload webhook di License Key](/developer-resources/webhooks/intents/license-key).

<Tip>
  Per le nuove integrazioni, ascolta `entitlement_grant.delivered` piuttosto che `license_key.created`. L'evento di diritto ti informa che la consegna è completa su tutte le integrazioni del prodotto, non solo sulla chiave di licenza.
</Tip>

***

## Chiavi di Licenza Legacy

<Note>
  I prodotti creati con la vecchia flag `license_key_enabled` sono stati **automaticamente migrati** a un diritto di chiave di licenza. La migrazione è trasparente: le chiavi dei clienti esistenti continuano a funzionare inalterate, gli endpoint pubblici `/licenses/activate`, `/licenses/validate`, `/licenses/deactivate` continuano a funzionare e gli endpoint API `/license_keys/*` continuano a leggere e scrivere nello stesso archivio di chiavi.

  La sezione **License Keys** della dashboard autonoma rimane disponibile come elenco piatto di ogni chiave emessa, utile per audit e ricerca. La nuova configurazione (cambiando limiti di attivazione, durate o istruzioni) dovrebbe essere effettuata modificando il diritto di chiave di licenza migrato sotto **Entitlements**.
</Note>

***

## Best Practices

* **Mantieni chiari i limiti di attivazione**: Scegli impostazioni predefinite sensate (1 per applicazioni a singolo utente, 3-5 per licenze di team) e documentale.
* **Fornisci istruzioni di attivazione precise**: I clienti le copiano dalla loro email, quindi percorsi e comandi esatti risparmiano ticket di supporto.
* **Convalida le chiavi lato server**: Per prodotti connessi in rete, convalida tramite `/licenses/validate` piuttosto che memorizzare localmente l'attivazione.
* **Utilizza i webhook per la revoca**: Ascolta `entitlement_grant.revoked` per disabilitare immediatamente le funzionalità in-app quando un cliente annulla o richiede un rimborso.
* **Testa con abbonamenti e acquisti una tantum**: Il comportamento delle chiavi di licenza differisce sottilmente tra i due, quindi testa entrambi prima di andare in produzione.