身份验证

除POST /partner-applications*和POST /api-keys/bootstrap外，所有受保护的 API 路由都需要 Bearer 密钥。请将密钥保存在服务器端并遵循最小权限原则。详情请参阅安全最佳实践。

请求头

请求头	必需	示例	说明
`Authorization`	是	`Bearer nsp_live_xxx`	Bearer API 密钥。所有受保护路由均必需。
`X-NU-Partner-Id`	否	`org_xxx`	可选断言。如提供，必须与密钥推导出的组织一致。
`X-NU-Request-Id`	否	`req_01HQ...`	用于追踪和受支持幂等写入的可选稳定请求 ID。
`Accept-Language`	否	`ja-JP, en;q=0.8`	选择供人阅读的 API 错误消息语言。不支持或省略的值将回退为英语。

curl "https://signal-partners.newunivers.ai/v1/catalog/titles" \
  -H "Authorization: Bearer nsp_live_xxxxxxxxxxxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "X-NU-Request-Id: req_01HQABCDEF" \
  -H "Accept-Language: ja-JP, en;q=0.8"

Accept-Language仅影响供人阅读的消息。请从Content-Language读取所选语言；缓存必须遵循Vary: Accept-Language。稳定的error.code和details[].issue标记不会随语言变化。

Content-Language: ja
Vary: Accept-Language

Bearer 密钥

请按签发内容原样发送密钥。密钥仅显示一次，绝不能放入浏览器代码、URL 或日志。详情请参阅API 密钥。

X-NU-Partner-Id

组织由 API 密钥安全推导。不匹配的断言会被拒绝并返回 invalid_api_key。除非集成需要显式一致性检查，否则请省略此请求头。

X-NU-Request-Id

请提供稳定值以关联日志，API 会通过 error.request_id 回显该值。该值还为 POST /playback/tokens、POST /licenses/requests 和 POST /api-keys/{id}/rotate 提供幂等性。已完成请求的重试会重放原始响应；仍在处理的并发重复请求返回 409 conflict。

身份验证与授权错误

情况	HTTP	error.code
密钥缺失或格式错误	401	`invalid_api_key`
未知、过期或环境不匹配的密钥	401	`invalid_api_key`
已吊销密钥	401	`api_key_revoked`
缺少所需作用域	403	`missing_scope`
在仅限 Production 的路由上使用 Sandbox 密钥	403	`production_key_required`
组织尚未获批	403	`organization_not_approved`
权利、地区或剧集未获授权	403	`license_not_active / territory_not_allowed / episode_not_licensed`

401 表示凭据本身不可用。403 表示密钥已识别，但无权执行此操作。详情请参阅错误代码。

作用域

作用域	权限
`catalog:read`	读取可见的目录作品、Experience 和剧集。
`license:read`	请求报价并读取授权协议。
`license:write`	创建授权请求。
`api_keys:read`	列出 API 密钥但不含密钥值。
`api_keys:write`	创建、更新、轮换和吊销 API 密钥。
`playback:token`	创建播放令牌，并查看或吊销会话。
`events:write`	发送单个或批量事件。
`settlement:read`	读取 Production 结算单和明细。
`settlement:dispute`	提出结算异议。

请按工作负载分离密钥，并仅授予各组件所需的作用域。api_keys:write 应仅保留在保险库中的运维密钥上，不要授予播放或事件运行时密钥。