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

# Chaves de Licença

> Gere e entregue chaves de licença únicas com limites de ativação e expiração. As chaves de licença são o tipo de direito de Chave de Licença. Elas são emitidas automaticamente no pagamento, vinculadas ao ciclo de vida da assinatura e revogadas no cancelamento ou reembolso.

<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>
  As chaves de licença são o tipo de direito de Chave de Licença. Crie um direito de Chave de Licença uma vez com o limite de ativação, expiração e instruções desejadas, anexe a qualquer produto, e o Dodo Payments gera e entrega uma chave por compra ou assento de assinatura, automaticamente.
</Info>

## O que são Chaves de Licença?

Chaves de licença são tokens únicos que autorizam o acesso ao seu produto. Elas são ideais para:

* **Licenciamento de software**: Aplicativos de desktop, plugins e CLIs
* **Controles por usuário**: Limitar ativações por usuário ou dispositivo
* **Bens digitais**: Restringir downloads, atualizações ou recursos premium

Dentro do Dodo Payments, as chaves de licença são gerenciadas através do sistema de [Entitlements](/features/entitlements/introduction), o que significa que o ciclo de vida de cada chave (criação, expiração, revogação, reatribuição) é conduzido pelos mesmos eventos de pagamento e assinatura que seus outros produtos.

## Criar um Direito de Chave de Licença

<Steps>
  <Step title="Open Entitlements">
    Vá para **Entitlements** no seu painel do Dodo Payments e clique em **+** para criar um novo direito.
  </Step>

  <Step title="Choose License Key">
    Selecione **License Key** como a integração. Configure como cada chave emitida deve se comportar:

    * **Limite de Ativações**: Máximo de ativações simultâneas por chave (por exemplo, `1` para usuário único, `5` para licenças de equipe, deixar em branco para ilimitado).
    * **Duração**: Quanto tempo a chave permanece válida após a emissão (por exemplo, 30 dias, 1 ano). Para chaves emitidas por assinatura, deixe em branco; as chaves permanecem válidas enquanto a assinatura estiver ativa.
    * **Instruções de Ativação**: Instruções orientadas ao cliente enviadas por e-mail com a chave. Exemplos: `Paste the key in Settings → License` ou `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="Novo formulário de direitos de Chave de Licença com nome, modo de cumprimento, duração da licença, limite de ativações e mensagem de ativação" style={{ maxHeight: '500px', width: 'auto' }} width="2840" height="1614" data-path="images/entitlements/license-keys/create.png" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Salvar. O direito agora está disponível para ser anexado a qualquer produto.
  </Step>
</Steps>

## Anexar a Produtos

Abra um produto, expanda **Configurações Avançadas → Direitos & Créditos**, e selecione seu direito de Chave de Licença. Um único produto pode entregar uma chave de licença junto com outros direitos (acesso ao Discord, downloads de arquivos, acesso ao repositório do GitHub, etc.) na mesma compra.

<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="Painel de direitos do produto com Chave de Licença selecionada" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1197" data-path="images/entitlements/attach-to-product.png" />
</Frame>

***

## Como as Chaves são Emitidas

A emissão de chaves segue o [ciclo de concessão](/features/entitlements/introduction#how-grants-work) padrão:

| Evento                                    | Comportamento                                                                                                              |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (uma vez)             | Gere uma chave por `quantity` comprado. A expiração da chave respeita a duração do direito.                                |
| `subscription.active`                     | Gere uma chave por assinatura `quantity` (assento). A chave não expira; a validade está vinculada ao status da assinatura. |
| `subscription.renewed`                    | Nenhuma operação. As chaves existentes persistem.                                                                          |
| `subscription.on_hold`                    | Desabilite as chaves. Elas se reativam quando a assinatura sai de espera.                                                  |
| `subscription.cancelled` / `expired`      | Desabilite as chaves permanentemente.                                                                                      |
| `subscription.plan_changed`               | Desabilite as antigas chaves; emita novas para o novo plano.                                                               |
| `refund.succeeded` (uma vez)              | Desabilite as chaves.                                                                                                      |
| Revogação manual via API/painel           | Desabilite as chaves com `revocation_reason: manual`. Estas não são automaticamente reemitidas na renovação da assinatura. |
| Chave de licença desabilitada diretamente | Revogue a concessão com `revocation_reason: license_key_disabled`. Reabilitar a chave reativa a concessão automaticamente. |

### Comportamento de Quantidade

* **Produtos por assinatura** emitem uma chave por assento (`subscriptions.quantity`).
* **Produtos únicos** emitem uma chave por item de linha do carrinho (`product_cart.quantity`).
* **Concessões manuais de API** emitem exatamente uma chave.

### Modo de cumprimento

Cada direito de Chave de Licença tem um `fulfillment_mode` que controla quem fornece a chave:

* **`auto`** (padrão): Dodo Payments gera e envia automaticamente a chave por e-mail após pagamento ou assinatura. Este é o comportamento descrito acima e se aplica quando `fulfillment_mode` é omitido.
* **`manual`**: A compra cria uma concessão `pending` sem chave, e você fornece cada valor de chave. Veja [Cumprimento Manual](#manual-fulfillment) abaixo.

***

## Cumprimento Manual

Por padrão, o Dodo Payments gera e envia por e-mail uma chave de licença assim que um cliente paga. Com o **cumprimento manual** você fornece a chave: a compra cria uma concessão `pending` sem chave, notifica você e aguarda a submissão do valor da chave. Use-o quando as chaves vierem do seu próprio sistema, de um fornecedor terceirizado ou de um estoque finito de códigos pré-impressos.

<Info>
  Procurando uma construção passo a passo? Veja o [Guia de Integração de Cumprimento Manual de Chave de Licença](/developer-resources/manual-license-key-fulfillment) para um passo a passo completo desde a criação do produto até a entrega da chave.
</Info>

### Quando usar

A execução automática é o padrão adequado para a maioria das licenças de software. Escolha o cumprimento manual quando o Dodo Payments não puder gerar a chave por conta própria:

* **Traga suas próprias chaves**: A chave é gerada por seu aplicativo, um produto de desktop ou seu próprio servidor de licenças.
* **Fornecedores terceiros**: Você revende chaves emitidas por um fornecedor upstream (uma chave de jogo, uma credencial de API, uma plataforma parceira).
* **Inventário finito**: Você distribui códigos de um pool pré-alocado e deseja atribuí-los um a um.
* **Revisão humana**: Você quer verificar uma compra antes de liberar o acesso.

### Habilitar cumprimento manual

Defina `fulfillment_mode: "manual"` na configuração de integração do direito da Chave de Licença:

<CodeGroup>
  ```typescript Node.js theme={null} theme={null}
  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',
    },
  });
  ```

  ```bash cURL theme={null} theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

<Note>
  `fulfillment_mode` é compatível com versões anteriores. Direitos criados antes de essa configuração existir não têm `fulfillment_mode` e continuam a se comportar como `auto`. A mudança para `manual` só afeta concessões criadas **após** a alteração; chaves já entregues não são tocadas.
</Note>

### Encontrar concessões aguardando cumprimento

Quando um cliente compra um produto em modo manual, a concessão é criada no status `pending` sem chave e um webhook [`entitlement_grant.created`](/developer-resources/webhooks/intents/entitlement-grant) é acionado com `integration_type: "license_key"` e `status: "pending"`. Você pode reagir a esse webhook ou consultar o endpoint [List Customer Grants](/api-reference/entitlements/list-customer-grants) com os filtros `integration_type` e `status`:

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

### Entregar a chave

Envie a chave com o endpoint [Fulfill License Key Grant](/api-reference/entitlements/fulfill-license-key). A concessão passa para `delivered` e o cliente recebe automaticamente a chave — o mesmo e-mail que receberia na execução automática.

```bash cURL theme={null} theme={null}
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"
  }'
```

`activations_limit` e `expires_at` são opcionais e voltam à configuração do direito quando omitidos. Cada concessão pode ser cumprida uma vez; tentar cumprir novamente uma concessão já cumprida retorna `409` em vez de emitir uma segunda chave.

<Check>
  Você não precisa enviar a chave por e-mail — a entrega acontece automaticamente quando a concessão é cumprida. Isso difere de [importar chaves](#import-existing-license-keys-via-api) via `POST /license_keys`, que intencionalmente **não** notifica o cliente.
</Check>

***

## Ativação, Validação, Desativação

Os endpoints de ativação/validação/desativação da API são **públicos** e não requerem chave de API. Use-os diretamente a partir de software de desktop, CLIs ou clientes baseados em navegador para verificar chaves em tempo de execução.

<Info>
  **Endpoints Públicos**: Os endpoints de ativação, desativação e validação de licença são públicos e não exigem chave de API. Chame-os diretamente de suas aplicações clientes sem expor suas credenciais de API.
</Info>

### Ativar uma licença

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

### Validar uma licença

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

### Desativar uma instância de ativação

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

***

## Gerenciar Chaves

Abra o direito de Chave de Licença no seu dashboard para ver cada concessão (uma linha por chave de cliente) com data de entrega, contagem de ativações e uma ação de revogação. Cada detalhe da concessão revela a chave de licença subjacente, validade, ativações usadas e o limite de ativações.

Você também pode listar concessões programaticamente:

```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 Chaves de Licença Existentes via API

Já tem chaves de licença em outro sistema? Use a API [Create License Key](/api-reference/licenses/create-license-key) para importá-las para o Dodo Payments. Isso permite migrar chaves existentes sem interromper seus clientes — eles continuam a ativar, validar e desativar usando as mesmas strings de chaves sem reemissão.

<Warning>
  Chaves de licença criadas ou atualizadas através da API não disparam notificações de e-mail para os clientes. Se precisar notificar os clientes sobre uma chave importada, cuide disso separadamente em sua aplicação.
</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',
});
```

### Como as chaves diferem por fonte

| Campo                            | Chave gerada automaticamente           | Chave cumprida manualmente                                              | Chave Importada                             |
| -------------------------------- | -------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------- |
| `source`                         | `"auto"`                               | `"manual"`                                                              | `"import"`                                  |
| Origem                           | Gerada pelo Dodo Payments no pagamento | [Fornecida por você](#manual-fulfillment) contra uma concessão pendente | Criada/migrada via `POST /license_keys`     |
| `payment_id`                     | Definida para o pagamento de origem    | Resolvida da concessão ou de sua assinatura                             | `null` (sem transação do Dodo Payments)     |
| `subscription_id`                | Definido se emitido via uma assinatura | Definido se a concessão veio de uma assinatura                          | `null` a menos que explicitamente vinculado |
| Notificação de e-mail do cliente | Enviada na emissão                     | Enviada no cumprimento                                                  | Não enviada — gerenciar separadamente       |

Use o campo `source` em respostas `GET /license_keys` para distinguir inventário migrado e chaves cumpridas manualmente de chaves emitidas organicamente ao reconciliar ou auditar.

<Tip>
  Migrando do **Polar.sh** ou **Lemon Squeezy**? O [`dodo-migrate` CLI](/migrate-to-dodo) automatiza importações em massa de produtos, clientes, descontos e chaves de licença em um único comando e mapeia IDs externos para IDs do Dodo automaticamente.
</Tip>

***

## Chaves de Licença na URL de Retorno

Quando um cliente conclui uma compra de um produto com direito a Chave de Licença, a chave gerada é automaticamente anexada à sua `return_url` como um parâmetro de consulta. Isso permite exibir a chave imediatamente na sua página de sucesso sem fazer uma chamada de API extra.

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

Se a compra gerar várias chaves (quantidade > 1), elas serão separadas por vírgulas:

```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 assinaturas, `subscription_id` é usado em vez 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
```

<Tip>
  Analise o parâmetro `license_key` na sua página de retorno para mostrar a chave imediatamente, melhorando a experiência pós-compra.
</Tip>

***

## Gerenciamento de API

<AccordionGroup>
  <Accordion title="Lifecycle Operations (Public Endpoints)">
    Ativação, desativação e validação são públicas; não é necessária chave de API.

    <CardGroup cols={3}>
      <Card title="Activate License" icon="code" href="/api-reference/licenses/activate-license">
        Crie ou registre uma instância de ativação para uma chave de licença.
      </Card>

      <Card title="Deactivate License" icon="code" href="/api-reference/licenses/deactivate-license">
        Revogue uma ativação anterior para liberar capacidade.
      </Card>

      <Card title="Validate License" icon="code" href="/api-reference/licenses/validate-license">
        Verifique a autenticidade, status e restrições antes de conceder acesso.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="License Key Management">
    Crie, liste, recupere e atualize registros individuais de chaves de licença. Use-os para importar chaves existentes ou buscar detalhes de uso.

    <CardGroup cols={2}>
      <Card title="Create License Key" icon="code" href="/api-reference/licenses/create-license-key">
        Crie uma nova chave de licença ou importe uma existente.
      </Card>

      <Card title="List License Keys" icon="code" href="/api-reference/licenses/list-license-keys">
        Navegue por todas as chaves com detalhes de status e uso.
      </Card>

      <Card title="Get License Key" icon="code" href="/api-reference/licenses/get-license-key">
        Recupere uma chave específica e seus metadados.
      </Card>

      <Card title="Update License Key" icon="code" href="/api-reference/licenses/update-license-key">
        Modifique a expiração, limites de ativação ou habilite/desabilite uma chave.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Entitlement Management">
    Gerencie o próprio direito de Chave de Licença: seu limite de ativação, duração e instruções.

    <CardGroup cols={2}>
      <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
        Crie um direito de Chave de Licença.
      </Card>

      <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
        Atualize a configuração do direito.
      </Card>

      <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
        Liste as chaves emitidas para um direito.
      </Card>

      <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
        Revogue manualmente a chave de um cliente.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

## Webhooks

Entrega e revogação de chave de licença disparam os quatro eventos [`entitlement_grant.*` de webhook](/developer-resources/webhooks/intents/entitlement-grant). A carga útil da concessão inclui um objeto `license_key` preenchido com a chave, validade, ativações usadas e limite.

Os eventos legados `license_key.*` (`license_key.created`) continuam a ser acionados para o ciclo de vida do registro de chave de licença subjacente; veja a [página de carga útil de webhook de Chave de Licença](/developer-resources/webhooks/intents/license-key).

<Tip>
  Para novas integrações, ouça `entitlement_grant.delivered` em vez de `license_key.created`. O evento de direito informa que a entrega está concluída em todas as integrações no produto, não apenas na chave de licença.
</Tip>

***

## Chaves de Licença Legadas

<Note>
  Produtos criados com a antiga flag `license_key_enabled` foram **automaticamente migrados** para um direito de Chave de Licença. A migração é transparente: as chaves dos clientes existentes continuam a funcionar inalteradas, os endpoints públicos `/licenses/activate`, `/licenses/validate`, `/licenses/deactivate` continuam a funcionar, e os endpoints da API `/license_keys/*` continuam a ler e a escrever na mesma loja de chaves.

  A seção autônoma **Chaves de Licença** no painel continua disponível como uma lista plana de todas as chaves emitidas, útil para auditoria e pesquisa. Nova configuração (alterando limites de ativação, durações ou instruções) deve ser feita editando o direito de Chave de Licença migrado em **Direitos**.
</Note>

***

## Melhores Práticas

* **Mantenha os limites de ativação claros**: Escolha padrões sensatos (1 para aplicativos de usuário único, 3-5 para licenças de equipe) e documente-os.
* **Forneça instruções de ativação precisas**: Os clientes copiam essas instruções de seus e-mails, então caminhos e comandos exatos economizam tickets de suporte.
* **Valide as chaves no lado do servidor**: Para produtos conectados à rede, valide via `/licenses/validate` em vez de armazenar a ativação localmente.
* **Use webhooks para revogação**: Ouça `entitlement_grant.revoked` para desativar funcionalidades no aplicativo imediatamente quando um cliente cancela ou solicita reembolso.
* **Teste com assinaturas e compras únicas**: O comportamento da chave de licença difere ligeiramente entre os dois, então teste ambos antes de ir ao ar.