API 密钥

API 密钥用于将您的服务器验证到 NU Signal Partners API。合作伙伴申请获批后，无需 Web 控制台即可通过 API 端点直接签发、轮换和吊销密钥。

获取首个密钥（bootstrap）

获批后，使用申请状态凭据调用 POST /partner-applications/claim，获得一次性批准令牌（前缀 nsp_appr_，有效 72 小时）。由于此时还没有 API 密钥，只有该端点公开并由此令牌保护。将其兑换为首个 Sandbox 密钥：

curl -X POST https://signal-partners.newunivers.ai/v1/api-keys/bootstrap \
  -H "Content-Type: application/json" \
  -d '{ "approval_token": "nsp_appr_..." }'

{
  "data": {
    "api_key_id": "ak_...",
    "key_prefix": "nsp_test_4f2a1b3c",
    "environment": "sandbox",
    "scopes": ["catalog:read", "license:read", "..."],
    "status": "active",
    "secret": "nsp_test_xxxxxxxx"
  }
}

批准领取和 bootstrap 令牌均在成功时消耗。第二次调用返回 401 invalid_approval_token。若丢失令牌，请联系 NU 重新签发。bootstrap 密钥包含管理作用域，可创建范围更窄的集成密钥。至少保留一个具有 api_keys:write 的服务端管理密钥；Production 运行时密钥通常不应具有密钥管理作用域。

API 密钥端点

方法与路径	所需权限	用途
`POST /v1/api-keys/bootstrap`	批准令牌	公开——使用批准令牌签发首个 Sandbox 密钥。
`GET /v1/api-keys`	`api_keys:read` 或 `api_keys:write`	列出密钥；绝不返回密钥值。
`POST /v1/api-keys`	`api_keys:write`	创建其他密钥。Production 需要具有 `production_api_enabled: true` 的 ACTIVE Production deal；否则返回 `license_not_active`。
`PATCH /v1/api-keys/{id}`	`api_keys:write`	更新 scopes、allowed_origins 或 allowed_ips。
`POST /v1/api-keys/{id}/rotate`	`api_keys:write`	签发替代密钥并吊销旧密钥。
`DELETE /v1/api-keys/{id}`	`api_keys:write`	吊销密钥。

Sandbox 与 Production 密钥

	Sandbox	Production
前缀	`nsp_test_`	`nsp_live_`
基础 URL	`https://signal-partners.newunivers.ai/v1`	`https://signal-partners.newunivers.ai/v1`
数据	隔离的模拟目录（isSandbox）	真实目录、deal 和收入
播放	无需授权	需要 ACTIVE 授权 deal
结算	无法访问真实财务结算单	查看并质疑结算

环境按密钥前缀、目录可见性、会话、日志和数据隔离。nsp_test_ 选择 Sandbox，nsp_live_ 选择 Production。每次请求都在密钥编码的环境中执行。

密钥值仅显示一次

完整密钥值仅在创建时返回一次。NU 只存储哈希，无法再次显示。请立即复制到密钥管理器。若丢失，请吊销并新建。

状态

状态	含义
`ACTIVE`	可用。
`REVOKED`	已手动停用。调用返回 `401 api_key_revoked`。
`EXPIRED`	已过期。调用返回 `401 invalid_api_key`。

轮换

POST /v1/api-keys/{id}/rotate 在一次调用中签发具有相同环境、作用域和限制的替代密钥，并吊销旧密钥。若需零停机轮换，请让密钥重叠使用：

使用相同作用域创建新密钥。
部署到服务器。
通过 X-NU-Request-Id 关联验证流量已切换到新密钥。
吊销旧密钥。

请定期并在怀疑泄露时立即轮换。吊销会将密钥标记为 REVOKED 并拒绝后续调用，但不会取消现有播放会话或令牌；它们按自身 TTL 过期。

吊销

吊销立即生效且不可逆。此后使用该密钥的所有调用均返回 401 api_key_revoked。

限制密钥使用位置

控制项	效果
`allowed_origins`	播放令牌仅为列表中的 origin 值签发。
`allowed_ips`	配置后，请求必须来自这些 IP 或 CIDR。
`scopes`	限制密钥可调用的端点（身份验证）。

上线前配置 allowed_origins 和 allowed_ips；这是 Production 检查清单的一部分。allowed_origins 之外的播放 origin 会在签发令牌时被拒绝。