跳转到主要内容

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.

许可证密钥是许可证密钥权限类型。创建一次许可证密钥权限，设置所需的激活限制、到期时间和说明，将其附加到任何产品，Dodo Payments会为每次购买或订阅自动生成和交付密钥。

​
什么是许可证密钥？

许可证密钥是授权访问您产品的唯一令牌。它们非常适合：
  • 软件许可：桌面应用程序、插件和命令行工具
  • 每用户控制：限制每个用户或设备的激活次数
  • 数字商品：限制下载、更新或高级功能
在 Dodo Payments 内，许可证密钥通过权限系统进行管理，这意味着每个密钥的生命周期（创建、到期、撤销、重新授予）由与其他交付物相同的付款和订阅事件驱动。

​
创建许可证密钥权限

1

Open Entitlements

在 Dodo Payments 仪表盘上进入 Entitlements，点击 + 创建新的权限。
2

Choose License Key

选择 License Key 作为集成。配置每个发放密钥的行为：
  • 激活限制：每个密钥的最大并发激活数（例如，1 对于单用户，5 对于团队许可证，留空为无限）。
  • 持续时间：密钥发放后保持有效的时间长度（例如，30 天，1 年）。对于订阅发放的密钥，留空；只要订阅有效，密钥仍然有效。
  • 激活说明：与密钥一起通过电子邮件发送给客户的说明。示例：Paste the key in Settings → License 或 Run: mycli activate <key>。
许可证密钥权限表单，包含激活限制、持续时间和说明
3

Save the entitlement

保存。该权限现在可附加到任何产品。

​
附加到产品

打开一个产品，展开 高级设置 → 权限和积分，然后选择您的许可证密钥权限。单个产品可以在同一购买中，与其他权限（Discord 访问、文件下载、GitHub 代码库访问等）一起交付许可证密钥。
产品权限面板，选择了许可证密钥

​
密钥如何发放

密钥的发放遵循标准的授权生命周期：
事件行为
payment.succeeded（一次性）为每个购买的 quantity 生成一个密钥。密钥到期时间遵循权限的持续时间。
subscription.active为每个订阅 quantity（席位）生成一个密钥。密钥没有到期时间；有效性与订阅状态相关。
subscription.renewed无操作。现有密钥继续有效。
subscription.on_hold禁用密钥。当订阅解除暂停时，它们会重新激活。
subscription.cancelled / expired永久禁用密钥。
subscription.plan_changed禁用旧密钥；为新计划发放新密钥。
refund.succeeded（一次性）禁用密钥。
通过 API/仪表盘手动撤销使用 revocation_reason: manual 禁用密钥。订阅续订时不会自动重新授予这些密钥。
直接禁用许可证密钥使用 revocation_reason: license_key_disabled 撤销权限。重新启用密钥会自动重新激活权限。

​
数量行为

  • 订阅产品 每个席位发放一个密钥（subscriptions.quantity）。
  • 一次性产品 每个购物车商品行发放一个密钥（product_cart.quantity）。
  • 手动 API 授权 精确发放一个密钥。

​
激活、验证、停用

激活/验证/停用 API 端点是公共的，不需要 API 密钥。直接从桌面软件、CLI 或基于浏览器的客户端使用它们以在运行时验证密钥。
公共端点：激活、停用和验证许可证的端点是公共的，不需要 API 密钥。在您的客户端应用程序中直接调用它们，而不暴露您的 API 凭据。

​
激活许可证

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

​
验证许可证

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

console.log(response.valid);

​
停用激活实例

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

​
管理密钥

从仪表盘打开许可证密钥权限，查看每个授权（每个客户密钥一行），包含交付日期、激活计数和撤销操作。每个授权详细信息显示底层许可证密钥、到期时间、已用激活和激活限制。 您还可以通过编程方式列出授权： 
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);
}

​
通过 API 导入现有许可证密钥

已经在另一个系统中拥有许可证密钥？使用创建许可证密钥API 将其导入 Dodo Payments。这样可以迁移现有密钥而不打扰您的客户 — 他们可以继续使用相同的密钥串进行激活、验证和停用，而无需重新发放密钥。
通过 API 创建或更新的许可证密钥不会触发客户电子邮件通知。如果您需要通知客户有关导入密钥，请在您的应用程序中单独处理此问题。
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',
});

​
导入的密钥与自动生成的密钥有何不同

字段自动生成的密钥导入的密钥
source"auto""import"
payment_id设置为原始支付null（没有 Dodo Payments 交易）
subscription_id如果密钥通过订阅发放则设置null 除非明确链接
客户电子邮件通知在发放时发送不发送 — 请单独处理
使用 source 字段在 GET /license_keys 响应中区分迁移的库存与有机发放的密钥，以便在对账或审核时使用。
从Polar.sh或Lemon Squeezy迁移？dodo-migrate CLI 自动化批量导入产品、客户、折扣和许可证密钥，并自动映射外部 ID 到 Dodo ID。

​
返回 URL 中的许可证密钥

当客户完成带有许可证密钥权限的产品的购买时，生成的密钥会自动作为查询参数附加到您的 return_url 以显示在成功页面上，而无需额外的 API 调用。 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
如果购买生成多个密钥（数量 > 1），它们是逗号分隔的： 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com
对于订阅，使用 subscription_id 而不是 payment_id： 
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com
在您的返回页面上解析 license_key 参数，以立即显示密钥，改进购买后的体验。

​
API 管理

激活、停用和验证都是公共的；无需 API 密钥。

Activate License

创建或记录许可证密钥的激活实例。

Deactivate License

撤销先前的激活以释放容量。

Validate License

在授予访问权限之前检查真实性、状态和限制。
创建、列出、检索和更新单个许可证密钥记录。使用这些来导入现有密钥或获取使用详情。

Create License Key

创建一个新的许可证密钥或导入现有密钥。

List License Keys

浏览所有密钥及其状态和使用详情。

Get License Key

检索特定密钥及其元数据。

Update License Key

修改到期时间、激活限制或启用/禁用密钥。
管理许可证密钥权限本身：其激活限制、持续时间和说明。

Create Entitlement

创建许可证密钥权限。

Update Entitlement

更新权限配置。

List Grants

列出为权限发放的密钥。

Revoke Grant

手动撤销客户的密钥。

​
Webhooks

许可证密钥的交付和撤销会触发四个entitlement_grant.* webhook 事件。授权负载包含一个填充的 license_key 对象，其中包含密钥、到期时间、已用激活和限制。 遗留的 license_key.* 事件（license_key.created）继续针对底层许可证密钥记录生命周期触发；参见许可证密钥 webhook 负载页面。
对于新的集成，监听 entitlement_grant.delivered 而不是 license_key.created。权限事件告诉您产品上的所有集成都完成了交付，而不仅仅是许可证密钥。

​
传统许可证密钥

使用早期 license_key_enabled 标志创建的产品已自动迁移到许可证密钥权限。迁移是透明的：现有客户的密钥继续正常工作，公共 /licenses/activate、/licenses/validate、/licenses/deactivate 端点继续运行，/license_keys/* API 端点继续读取和写入相同的密钥存储。独立的许可证密钥仪表盘部分仍可用，显示所有已发放的密钥，适用于审核和搜索。新的配置（更改激活限制、持续时间或说明）应通过在权限下编辑迁移后的许可证密钥权限来完成。

​
最佳实践

  • 保持激活限制明确：选择合理的默认值（单用户应用程序为 1，团队许可证为 3-5），并记录它们。
  • 提供精确的激活说明：客户从电子邮件中粘贴这些说明，精确的路径和命令可减少支持请求。
  • 服务器端验证密钥：对于联网产品，通过 /licenses/validate 验证，而不是本地缓存激活。
  • 使用 webhooks 进行撤销：监听 entitlement_grant.revoked，以便在客户取消或退款时立即禁用应用程序内功能。
  • 测试订阅和一次性购买：许可证密钥的行为在两者之间略有不同，因此在上线前测试两种情况。
Last modified on May 14, 2026