Authentication

All protected API routes require a bearer key except POST /partner-applications* and POST /api-keys/bootstrap. Keep keys on your server and apply least privilege. See Security best practices.

Request headers

Header	Required	Example	Notes
`Authorization`	Yes	`Bearer nsp_live_xxx`	Bearer API key. Required on every protected route.
`X-NU-Partner-Id`	No	`org_xxx`	Optional assertion. If supplied, it must match the organization derived from the key.
`X-NU-Request-Id`	No	`req_01HQ...`	Optional stable request ID for tracing and supported idempotent writes.
`Accept-Language`	No	`ja-JP, en;q=0.8`	Selects the language of human-readable API error messages. Unsupported or omitted values fall back to English.

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 affects only human-readable messages. Read the selected locale from Content-Language; caches must honor Vary: Accept-Language. Stable error.code and details[].issue tokens never change with locale.

Content-Language: ja
Vary: Accept-Language

Bearer key

Send the key exactly as issued. It is shown only once and must never be placed in browser code, URLs, or logs. See API keys.

X-NU-Partner-Id

The organization is derived securely from the API key. A mismatched assertion is rejected as invalid_api_key. Omit this header unless your integration needs an explicit consistency check.

X-NU-Request-Id

Supply a stable value to correlate logs. The API echoes it as error.request_id. It also provides idempotency for POST /playback/tokens, POST /licenses/requests, and POST /api-keys/{id}/rotate. Completed retries replay the original response; a concurrent duplicate still being processed returns 409 conflict.

Authentication and authorization errors

Situation	HTTP	error.code
Key missing or malformed	401	`invalid_api_key`
Unknown, expired, or environment-mismatched key	401	`invalid_api_key`
Revoked key	401	`api_key_revoked`
Required scope missing	403	`missing_scope`
Sandbox key used on a Production-only route	403	`production_key_required`
Organization not approved	403	`organization_not_approved`
Rights, territory, or episode is not authorized	403	`license_not_active / territory_not_allowed / episode_not_licensed`

401 means the credential itself is unusable. 403 means the key is known but lacks permission for this operation. See Error codes.

Scopes

Scope	Permission
`catalog:read`	Read visible catalog titles, experiences, and episodes.
`license:read`	Request quotes and read license agreements.
`license:write`	Create license requests.
`api_keys:read`	List API keys without secrets.
`api_keys:write`	Create, update, rotate, and revoke API keys.
`playback:token`	Create playback tokens and inspect or revoke sessions.
`events:write`	Send individual or batched events.
`settlement:read`	Read Production settlement statements and items.
`settlement:dispute`	Open settlement disputes.

Create separate keys per workload and grant only the scopes each component needs. Keep api_keys:write on a vault-held operational key, not on playback or event runtime keys.