API 키

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

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

NU가 신청을 승인하면 일회용 승인 토큰 (접두사 nsp_appr_, 72시간 유효)을 받습니다. 아직 API 키가 없으므로 이 엔드포인트만 공개되어 해당 토큰으로 게이트됩니다. 이를 첫 샌드박스 키로 교환하세요:

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

# 201 Created
{
  "data": {
    "api_key_id": "ak_...",
    "key_prefix": "nsp_test_4f2a1b3c",
    "environment": "sandbox",
    "scopes": ["catalog:read", "license:read", "..."],
    "status": "active",
    "secret": "nsp_test_xxxxxxxx"   // shown once — store it now
  }
}

토큰은 성공 시 소진됩니다. 두 번째 호출은 401 invalid_approval_token을 반환합니다. 승인 토큰을 분실했다면 NU에 재발급을 요청하세요. 부트스트랩 키는 관리 스코프를 포함하므로 더 좁은 연동 키를 생성할 수 있습니다. api_keys:write 스코프를 가진 서버 측 관리 키를 최소 하나는 유지하세요. 프로덕션 런타임 키는 일반적으로 API 키 관리 스코프를 포함하지 않아야 합니다.

API 키 엔드포인트

메서드 및 경로	필수 권한	용도
`POST /v1/api-keys/bootstrap`	승인 토큰	공개 — 승인 토큰으로 발급받는 첫 샌드박스 키.
`GET /v1/api-keys`	`api_keys:read` 또는 `api_keys:write`	키 목록 조회 (시크릿은 절대 반환되지 않음).
`POST /v1/api-keys`	`api_keys:write`	다른 키 생성. 프로덕션은 `production_api_enabled: true`인 ACTIVE 프로덕션 거래가 필요하며, 그렇지 않으면 `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`	키 폐기.

샌드박스 키와 프로덕션 키

	샌드박스	프로덕션
접두사	`nsp_test_`	`nsp_live_`
기본 URL	`https://nu-signal-partners.vercel.app/v1`	`https://nu-signal-partners.vercel.app/v1`
데이터	격리된 더미 카탈로그 (isSandbox)	실제 카탈로그, 거래, 매출
재생	라이선스 불필요	ACTIVE 라이선스 거래 필요

환경은 키 접두사, 카탈로그 가시성, 세션, 로그, 데이터별로 격리됩니다. nsp_test_ 키는 샌드박스로, nsp_live_ 키는 프로덕션으로 지정하세요. API는 키에 인코딩된 환경에서 각 요청을 처리합니다.

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

키를 생성하면 전체 시크릿이 생성 시점에 딱 한 번만 반환됩니다. 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은 재생 토큰 발급 시 거부됩니다.