API 키

API 키는 귀하의 서버를 NU Signal Partners API에 인증합니다. 파트너 신청이 승인되면 웹 콘솔 없이 API 엔드포인트에서 키를 직접 발급, 회전 및 폐기할 수 있습니다.

첫 키 발급받기(부트스트랩)

승인 후 신청 상태 자격증명으로 POST /partner-applications/claim을 호출하여 일회용 승인 토큰(접두사 nsp_appr_, 72시간 유효)을 받습니다. 아직 API 키가 없으므로 이 엔드포인트만 공개되고 해당 토큰으로 보호됩니다. 이를 첫 Sandbox 키로 교환하세요:

curl -X POST https://signal-partners.newunivers.ai/v1/api-keys/bootstrap \
  -H "Content-Type: application/json" \
  -d '{ "approval_token": "nsp_appr_..." }'

{
  "data": {
    "api_key_id": "ak_...",
    "key_prefix": "nsp_test_4f2a1b3c",
    "environment": "sandbox",
    "scopes": ["catalog:read", "license:read", "..."],
    "status": "active",
    "secret": "nsp_test_xxxxxxxx"
  }
}

승인 클레임과 부트스트랩 토큰은 각각 성공 시 소진됩니다. 두 번째 호출은 401 invalid_approval_token를 반환합니다. 토큰을 분실하면 NU에 재발급을 요청하세요. 부트스트랩 키는 더 좁은 연동 키를 만들 수 있는 관리 스코프를 포함합니다. api_keys:write를 가진 서버 측 관리 키를 최소 하나 유지하고 Production 런타임 키에는 일반적으로 키 관리 스코프를 부여하지 마세요.

API 키 엔드포인트

메서드 및 경로	필수 권한	용도
`POST /v1/api-keys/bootstrap`	승인 토큰	공개 — 승인 토큰으로 첫 Sandbox 키를 발급합니다.
`GET /v1/api-keys`	`api_keys:read` 또는 `api_keys:write`	키 목록을 조회하며 시크릿은 절대 반환하지 않습니다.
`POST /v1/api-keys`	`api_keys:write`	다른 키를 생성합니다. Production에는 `production_api_enabled: true`인 ACTIVE Production 딜이 필요하며 그렇지 않으면 `license_not_active`를 반환합니다.
`PATCH /v1/api-keys/{id}`	`api_keys:write`	scopes, allowed_origins 또는 allowed_ips를 수정합니다.
`POST /v1/api-keys/{id}/rotate`	`api_keys:write`	대체 키를 발급하고 기존 키를 폐기합니다.
`DELETE /v1/api-keys/{id}`	`api_keys:write`	키를 폐기합니다.

Sandbox 및 Production 키

	샌드박스	프로덕션
접두사	`nsp_test_`	`nsp_live_`
기본 URL	`https://signal-partners.newunivers.ai/v1`	`https://signal-partners.newunivers.ai/v1`
데이터	격리된 더미 카탈로그(isSandbox)	실제 카탈로그, 딜 및 매출
재생	라이선스 불필요	ACTIVE 라이선스 딜 필요
정산	실제 금융 정산서 접근 불가	정산 조회 및 이의 제기 가능

환경은 키 접두사, 카탈로그 가시성, 세션, 로그 및 데이터별로 격리됩니다. nsp_test_는 Sandbox, nsp_live_는 Production을 선택합니다. 모든 요청은 키에 인코딩된 환경에서 처리됩니다.

시크릿은 한 번만 표시됩니다

전체 시크릿은 키 생성 시 딱 한 번 반환됩니다. NU는 해시만 저장하므로 다시 표시할 수 없습니다. 즉시 시크릿 매니저에 복사하세요. 분실하면 폐기 후 새 키를 생성하세요.

상태

상태	의미
`ACTIVE`	사용 가능.
`REVOKED`	수동으로 비활성화됨. 호출 시 `401 api_key_revoked`를 반환합니다.
`EXPIRED`	만료됨. 호출 시 `401 invalid_api_key`를 반환합니다.

회전

POST /v1/api-keys/{id}/rotate는 동일한 환경, 스코프 및 제한을 가진 대체 키를 발급하고 한 번의 호출로 기존 키를 폐기합니다. 무중단 회전은 키를 겹쳐 사용하세요:

동일한 스코프로 새 키를 생성합니다.
서버에 배포합니다.
X-NU-Request-Id 연계를 통해 트래픽이 새 키로 전환되었는지 확인합니다.
기존 키를 폐기합니다.

정기적으로 그리고 노출이 의심되면 즉시 회전하세요. 폐기하면 키가 REVOKED로 표시되고 이후 호출이 거부되지만 기존 재생 세션이나 토큰은 취소되지 않으며 각 TTL에 따라 만료됩니다.

폐기

폐기는 즉시 적용되며 되돌릴 수 없습니다. 이후 해당 키로 보낸 모든 호출은 401 api_key_revoked를 반환합니다.

키 사용 위치 제한

제어	효과
`allowed_origins`	재생 토큰은 목록에 있는 origin 값에 대해서만 발급됩니다.
`allowed_ips`	설정 시 요청은 지정된 IP 또는 CIDR에서 시작되어야 합니다.
`scopes`	키가 호출할 수 있는 엔드포인트를 제한합니다(인증).

출시 전에 allowed_origins와 allowed_ips를 설정하세요. 이는 프로덕션 체크리스트의 일부입니다. allowed_origins 밖의 재생 origin은 토큰 발급 시 거부됩니다.