認証

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は再生・イベントのランタイムキーではなく、保管庫に保存した運用キーだけに付与します。