管理 API Key

当你希望自己的订单系统自动签发许可证，或从服务器读取授权数据时，使用管理 API Key。它代表你的厂商工作空间。

客户端需要的是哪一种密钥？

凭证	交给谁	用来做什么
`lv_api_…` 管理 API Key	你自己的服务器	创建产品、策略和许可证，查看设备、用量和审计记录
`lv_lic_…` 许可证密钥	客户的软件	激活、验证、发送心跳和释放当前设备
产品公钥	随客户端发布	检查服务器返回的授权签名是否有效

如果你只接入客户软件的授权验证，使用许可证密钥就够了。管理 API Key 可以操作整个工作空间，不能放进客户软件或公开网页。

创建一个 Key

用工作空间 Owner（所有者）账号登录，打开 API Key，点击“创建 API Key”。
名称填它的用途，例如“订单系统”。只查询时选“只读”；要创建或修改许可证时选“读写”。有效期可设为 1–365 天。
保存后立即复制完整 Key，它只显示一次。把它放在你服务器的私有配置或环境变量中。

发送第一个管理请求

示例读取产品列表。将 LICENTIVO_URL 设置为授权服务器地址，将 LICENTIVO_API_KEY 设置为刚创建的完整 Key，再执行：

curl "$LICENTIVO_URL/api/v1/products?limit=25" \
  -H "Authorization: Bearer $LICENTIVO_API_KEY"

这是 Bash / macOS / Linux 的写法。Windows PowerShell 请使用 curl.exe，环境变量用 $env:LICENTIVO_URL 和 $env:LICENTIVO_API_KEY。九种语言的完整请求代码也放在 SDK 页的“服务端管理 API Key”选项中。

成功时返回 HTTP 200，正文包含 data.items。使用 Bearer Key 的管理请求不需要登录 Cookie 或 CSRF Token。

权限和失效处理

只读 Key 能查看资源；读写 Key 还能创建和修改产品、策略、许可证。管理 Key 不用于账号、团队、系统设置或收款操作，这些操作需要相应账号登录。

Key 泄漏或不再使用时，在控制台吊销；需要更换时点击“轮换”。旧 Key 会立即失效，随后更新你服务器上的配置。

套餐中的 API 调用额度统计激活、验证、心跳和释放。这里的管理请求不计入这项额度。

通用请求与响应约定

项目	约定
服务器地址	`LICENTIVO_URL` 为授权服务器根地址；接口路径统一以 `/api/v1` 开头。
认证	`Authorization: Bearer YOUR_MANAGEMENT_API_KEY`。只读为 `scope=read`，读写为 `scope=write`；Key 仅能访问所属工作空间，写操作还要求创建者当前为有效 Owner。
JSON 正文	有正文时必须发送 `Content-Type: application/json`，正文上限 64 KiB。未知字段、多个 JSON 对象和错误类型会被拒绝；标为 `{}` 的操作也必须发送空对象。GET 和 DELETE 不发送正文。
修改字段	PATCH 省略的字段保留原值；基础修改接口至少提供一个可修改字段。条件必填规则见字段说明，例如限期许可证的 `duration_days`。
成功与失败	JSON 成功响应为 `{"data": ..., "request_id": "..."}`；失败响应为 `{"error": {"code": "...", "message": "..."}, "request_id": "..."}`。创建一般返回 201，查询和修改一般返回 200，任务入队返回 202。
文件响应	CSV 和 ZIP 成功时直接返回文件，没有 `data` 包装；失败仍返回 JSON。响应头 `X-Request-ID` 可用于追踪请求。
分页	支持分页的接口默认 `limit=25`、`offset=0`；范围分别为 1–100 和 0–100000。通常返回 `items` 和 `total`，分页参数是否回显以接口字段表为准；审计记录不返回 total。下一页增加 offset，少于 limit 条时停止。未列出的筛选参数不应依赖。
时间与金额	日期字符串使用 UTC / RFC 3339；离线申请的 `created_at` 为 Unix 秒。金额 `_cents` 为百分之一货币单位，`_micros` 为百万分之一，均结合 `currency` 读取。

重试与幂等

普通创建、续期和密钥轮换不提供通用 Idempotency-Key 去重；超时后不要直接重发，以免重复签发或续期。需要可靠重试的订单系统可使用 POST /api/v1/licenses/batch：每个订单生成并保存正文 request_id，重试沿用原 ID 和完全相同的内容。一键接入也使用正文 request_id 去重。

响应顶层的 request_id 与业务去重 ID 分开：前者每次 HTTP 请求由服务器生成，后者由你为同一次业务操作保存。202 表示已接受任务，请继续查询任务状态；429 按 Retry-After 等待；5xx 或断网后的写入结果可能不确定，先查询或按该接口的幂等规则恢复。

管理接口错误码与处理

HTTP / error.code	原因与处理
`400 INVALID_INPUT` `415 JSON_REQUIRED`	修正字段、条件必填项或 Content-Type；不应原样重试。
`401 UNAUTHENTICATED`	Key 格式不正确、已到期、已吊销，或所属账号、工作空间已失效。检查完整 Key 与账号状态。
`403 FORBIDDEN` `403 CSRF_INVALID`	检查 scope、Owner 角色与登录会话要求；Cookie 写操作的 CSRF Token 必须匹配当前会话。
`404 NOT_FOUND` `405 METHOD_NOT_ALLOWED`	检查资源 ID、所属工作空间、是否已归档以及 HTTP 方法；405 的 Allow 响应头列出允许的方法。
`409 PRODUCT_DISABLED` `409 RESOURCE_IN_USE`	先启用产品；归档产品或策略前先处理其关联资源。
`409 LICENSE_REVOKED` `409 PERPETUAL_LICENSE`	已吊销许可证不能恢复或续期；永久许可证无需延长使用有效期。
`409 DEVICE_LIMIT_BELOW_ACTIVE` `409 ACTIVE_DEVICES_CONFLICT`	先释放超出新上限的设备或会话，再减少名额或切换授权模式。
`409 POLICY_CHANGED` `409 PREVIEW_STALE`	重新读取策略版本或重新预览变更，再提交；不要覆盖其他操作产生的新状态。
`409 IDEMPOTENCY_CONFLICT`	相同业务 request_id 被用于不同内容。重试必须保留原 ID 和正文；新的业务操作生成新 ID。
`409 KEY_LIMIT` `409 KEY_INACTIVE`	最多 100 个有效 Key；先吊销不用的 Key。只有有效且创建者仍为有效 Owner 的 Key 才能轮换。
`409 PLAN_VERSION_CONFLICT` `409 INVOICE_STATE_CONFLICT` `409 JOB_STATE_CONFLICT`	重新读取价格、账单或任务状态后再操作；只有 failed 的计费任务可重试。
`409 DELIVERY_RUNNING` `409 WEBHOOK_DISABLED`	等待正在执行的投递结束，或先启用事件订阅；接收端应按事件 ID 去重。
`413 EXPORT_TOO_LARGE` `429 RATE_LIMITED`	缩小导出范围到 5000 条以内，或使用分页接口；限流时按 Retry-After 等待。
`500 INTERNAL_ERROR` `503 DEFAULT_PLAN_DISABLED`	保留 request_id 排查；默认额度未启用时联系管理员。写入结果不确定时，先按幂等规则核对，避免重复业务。

离线授权还可能返回客户端授权错误，具体原因见常见问题与授权错误。

专业术语对照

术语	中文名称与含义
`authentication / authorization`	身份认证 / 权限校验：先验证凭证代表谁，再检查是否允许当前操作。
`scope`	权限范围：read 为只读，write 为读写；与账号的 Owner / read_only 角色分开。
`policy / plan / purchase`	授权策略 / 计费方案 / 套餐购买合同：分别管理软件授权规则、服务价格和已购权益。
`license / license key`	许可证 / 许可证密钥（授权码）：前者是管理记录，后者是客户激活使用的秘密，均不同于管理 API Key。
`activation / seat / lease`	激活记录 / 席位 / 授权租约：分别表示设备或会话记录、并发使用名额、服务器签名的有期限授权内容。
`revoke / suspend / archive / release`	吊销 / 暂停 / 归档 / 释放：吊销不可恢复，暂停可恢复，归档移出正常查询，释放归还设备或席位。
`rotate / idempotency / reservation`	轮换 / 幂等 / 预留：分别表示更换密钥、重复同一业务操作不产生额外效果、先占用功能次数再确认扣除。

全部管理请求与响应

下方覆盖所有支持 Bearer Key 的操作，并单列创建、查询、轮换和吊销 Key 所需的 Owner 登录会话接口。选择接口即可查看完整调用、成功响应、全部字段及条件。示例数据仅用于说明，不是可直接使用的凭证。

正在加载接口参考…

管理 Key 的权限边界

只读 Key 可调用目录中标记“只读 / 读写 Key”的接口，读写 Key 还能执行标记“读写 Key”的操作。Key 生命周期、账号、成员、系统设置、付款与退款接口需要相应登录会话。月度账单查询和任务操作以目录列出的实际权限为准。客户激活、验证、心跳、计次和解绑使用客户授权凭证，见 SDK 授权调用。

机器可读契约可下载 OpenAPI JSON（当前语言），用于导入 Postman 等工具。网页字段解释随当前文档语言显示。