인증

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는 재생 또는 이벤트 런타임 키가 아니라 볼트에 보관된 운영 키에만 유지하세요.