인증

POST /partner-applications와 POST /api-keys/bootstrap를 제외한 모든 엔드포인트는 인증이 필요합니다. 반드시 서버 측에서만 인증하세요. API 키를 브라우저나 모바일 클라이언트로 전송해서는 안 됩니다 (보안 모범 사례 참고).

필수 헤더

헤더	필수	예시	비고
`Authorization`	예	`Bearer nsp_live_xxx`	Bearer API 키. 샌드박스 키는 nsp_test_로, 프로덕션 키는 nsp_live_로 시작합니다.
`X-NU-Partner-Id`	아니오	`org_xxx`	선택 사항. 전송할 경우 키의 조직과 일치해야 하며, 불일치 시 거부됩니다. 생략해도 무방합니다 — 키가 이미 조직을 식별합니다.
`X-NU-Request-Id`	아니오	`req_01HQ...`	클라이언트가 생성한 추적 ID. 재생 토큰 및 라이선스 요청 생성 시 멱등 키로도 사용됩니다.

curl "https://nu-signal-partners.vercel.app/v1/catalog/titles" \
  -H "Authorization: Bearer nsp_live_xxxxxxxxxxxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "X-NU-Request-Id: req_01HQABCDEF"

Bearer 키

키는 자체 환경(nsp_test_ 대 nsp_live_)을 인코딩하며 단일 조직에 바인딩됩니다. 샌드박스와 프로덕션은 서로 다른 기본 URL을 사용합니다. 요청별 환경 게이트는 없으며, 키가 자체 환경을 담고 있어 모든 요청이 해당 환경에서 처리됩니다. 키는 호출할 수 있는 엔드포인트를 제어하는 스코프를 포함합니다. 관리, 회전, 폐기는 API 키에서 다룹니다.

X-NU-Partner-Id

선택 사항입니다. 키 자체가 이미 조직을 식별하므로 이 헤더는 필수가 아닙니다. 전송할 경우 키가 발급된 조직과 동일한 조직을 참조해야 하며, 불일치 시 invalid_api_key로 거부됩니다. 헤더가 없으면 통과합니다. 카탈로그 가시성, 라이선스 거래, 이벤트, 정산은 헤더 유무와 관계없이 키의 조직으로 스코프됩니다.

X-NU-Request-Id

선택 사항이지만 권장됩니다. 논리적 요청마다 고유한 값을 제공하면 귀하의 로그를 NU의 로그와 연결할 수 있으며, 실패 시 error.request_id 로 그대로 반환됩니다. POST /playback/tokens, POST /licenses/requests, POST /api-keys/{id}/rotate에서 멱등 윈도우 내에 같은 값을 재사용하면 완료된 응답이 재생되거나, 첫 요청이 아직 처리 중이면 409 conflict를 반환합니다.

401과 403 동작

상황	HTTP	error.code
키 누락 / 형식 오류 / 알 수 없는 키	401	`invalid_api_key`
키 만료, 또는 X-NU-Partner-Id 불일치	401	`invalid_api_key`
키가 폐기됨	401	`api_key_revoked`
인증되었으나 키에 스코프가 없음	403	`missing_scope`
조직이 아직 승인되지 않음	403	`organization_not_approved`
라이선스 / 지역 / 에피소드가 인가되지 않음	403	`license_not_active / territory_not_allowed / episode_not_licensed`

401은 "인증할 수 없음"을 의미합니다. 403은 "인증되었으나 인가되지 않음"을 의미합니다. 전체 매핑은 오류 코드를 참고하세요.

스코프

스코프	권한
`catalog:read`	타이틀 및 에피소드 조회
`license:read`	라이선스 견적 및 거래 조회
`license:write`	라이선스 요청 생성
`api_keys:read`	API 키 목록 조회
`api_keys:write`	API 키 생성, 수정, 회전, 폐기
`playback:token`	재생 토큰 발급, 세션 조회
`events:write`	단일 및 배치 이벤트 전송
`settlement:read`	정산 및 항목 조회
`settlement:dispute`	정산 분쟁 제기

각 연동 구성 요소에 필요한 최소한의 스코프만 부여하세요.