인증
이해하기
본 가이드는 인증 토큰 획득에 대해 안내합니다.
server API를 사용하려면 인증을 해야 하며, 인증방식은 액세스 토큰 발급을 통한 인증방식을 사용합니다.
2026.10.29 이후 등록된 앱은 장기 토큰 발급이 불가합니다. 기존 장기 토큰을 발급한 사용자는 2027.06.30 까지 서버 토큰으로 전환해야 하며, 2027.07.01 부터 장기 토큰으로 server API 호출이 불가합니다.
[목차]
용어 정의
| 용어 | 설명 |
|---|---|
| system Key | 시스템키 (외부시스템 연동을 위한 API호출키) - systemKey를 필수 파라미터로, 각 솔루션별 server API를 통신 - 앱 기준으로 systemKey 발급 - 서버/장기/단기 토큰 발급API Request body 내 client_id 값 |
| secret Key | 앱 인증에 필요한 값 - 액세스 토큰(Access Token) 발급 요청 시 system Key와 함께 사용 - 서버/장기/단기 토큰 발급API Request body 내 client_secret 값 |
| authorization Code | 장기/단기 토큰을 발급하기 위해 필요한 인증코드 - 장기/단기 토큰 발급API Request body 내 code 값 ※ 서버 토큰 발급 시 미사용 |
| shop_no | 쇼핑몰(상점) 식별자 - 서버 토큰 발급 및 갱신 시 사용 값 - 서버 토큰 발급 API Request body 내 shop_no 값 |
| partner_no | 파트너(공급사) 식별자 - 샵바이 전용 - 서버 토큰 발급 및 갱신 시 사용 값 - 서버 토큰 발급 API Request body 내 partner_no 값 |
| access Token | server API를 호출하기 위해 인증서버에서 검증하는 토큰 - 앱의 목적에 따라 서버/장기/단기 토큰을 발급받는 API 호출 가능 - 서버/장기/단기 토큰 발급 API Responses 내 access_token 값 - server API 호출 시 Request Header 내 Authorization 값 |
| refresh Token | 단기 토큰 만료 시 이를 갱신하기 위한 용도로 사용되는 토큰 - access Token보다 토큰 만료기간이 김 - 단기 토큰 발급 API Responses로 받는 refresh_token |
| redirect URI | 장기/단기 토큰 발급을 위한 검증용 파라미터로, 필수 입력값입니다. 반드시 HTTPS 프로토콜을 사용해야 합니다. |
[systemKey 및 secretKey 확인 방법]
아래 인증정보 영역을 통해 server API 호출에 필요한 systemKey와 secretKey를 확인합니다.
▼ 화면 경로: 셀러어드민 > 상품 > 앱 > 앱 수정
인증 프로세스
[앱 실행]
쇼핑몰 관리자에서 설치된 앱의 '실행' 버튼을 클릭하면 인증 프로세스가 시작됩니다.
▼ 화면 경로: 쇼핑몰 관리자 > 앱 서비스 > 앱 서비스 > 설치 리스트
- [정보 확인]
- 실행 버튼을 누르면 토큰 발급 시 필요한 'authorizationCode', 'shop_no', 'partner_no'를 아래와 같이 request parameter로 전달합니다.
앱 실행 링크:https://{앱 등록 시 입력한 앱URI}?code=${authorizationCode}&solution=${shopby 또는 godo}&shop_no=${shop_no}&partner_no=${partner_no}
앱 실행 링크 내 쇼핑몰 식별자(shop_no)와 파트너 식별자(partner_no)는 서버 토큰으로 전환하였거나, 2026.10.29 이후 등록된 앱에 한하여 전달하며, 파트너 식별자는 파트너(공급사) 관리자에서 앱을 실행한 경우에만 전달합니다. - [액세스 토큰 발급 요청]
- 앱의 systemKey, secretKey, redirectUri 그리고 앱 실행 시 request parameter로 전달된 정보를 활용하여 액세스 토큰(access token) 발급을 요청합니다.
필요에 따라 서버 토큰, 장기 토큰(fade-out 예정), 단기 토큰 발급 API를 호출하여 토큰을 발급합니다.
※ 서버 토큰과 장기 토큰은 발급을 포함한 모든 server API 호출이 앱에 등록된 IP에서만 허용되므로, 호출 서버의 IP가 셀러어드민에 등록되어 있어야 합니다.
토큰 유형(서버 토큰/장기 토큰(fade-out 예정)/단기 토큰)
토큰은 쇼핑몰 관리자에 설치된 앱을 기준으로 발급받을 수 있습니다.
쇼핑몰과 서버 토큰 및 장기 토큰의 관계는 1:1이며, 쇼핑몰과 단기 토큰의 관계는 1:n입니다.
1:1 관계를 갖는 서버 토큰과 장기 토큰은 신규로 발급받으면 이전에 발급된 토큰은 유효기간과 상관없이 폐기되어 해당 토큰으로는 더 이상 server API를 호출할 수 없습니다.
※ 파트너(공급사) 관리자에서 발급된 1:1 관계 토큰은 파트너(공급사)별로 구분되어 유지됩니다.
[토큰 유형별 비교]
| 구분 | 서버 토큰 | 장기 토큰 (fade-out 예정) | 단기 토큰 |
|---|---|---|---|
| 유효기간 | 24시간 | 100년 | 5분 (리프레시 토큰 24시간) |
| 쇼핑몰과의 관계 | 1:1 | 1:1 | 1:n |
| 발급 시 필요한 값 | shop_no, partner_no ※ authorizationCode 불필요 | authorizationCode | authorizationCode |
| IP 제한 | 등록된 IP에서만 server API 호출 가능 | 등록된 IP에서만 server API 호출 가능 | 등록한 IP가 아니어도 server API 호출 가능 |
| 갱신 | 만료 시 재발급 (최초 발급 프로세스와 동일) | 갱신 없음 (별도 refresh_token 없음) | 리프레시 토큰으로 갱신 |
- post서버 토큰 발급하기
- /oauth/token
인증 정보(client_id, client_secret)와 설치 정보(shop_no, partner_no)를 이용해서 access Token(24시간)을 발급받습니다.
- [특징]
- 외부 서버 등에서 데이터를 주기적으로 동기화하거나 server to server 통신을 위한 토큰입니다.
- 셀러어드민 앱 등록 시 입력한 IP에서만 server API를 호출할 수 있습니다.
- 서버 토큰(access_token)의 유효기간은 발급일시 기준으로 24시간입니다.
- 토큰의 유효기간(expire_in)이 만료되면 토큰을 다시 발급받아야 합니다. 재발급 프로세스는 최초 발급 프로세스와 동일합니다.
- [이런 경우 서버 토큰을 사용하세요]
- 외부 서버/어드민에서 주기적으로 데이터를 동기화해야 하는 경우
- 쇼핑몰 관리자에 접속하지 않은 상태에서, 서버 간의 주기적인 server API 호출이 필요한 경우
- 단기 토큰을 사용하여 API 호출 시마다 계속 토큰을 갱신하는 것이 적합하지 않은 경우
- [발급 방법 (request body)]
항목명 필수여부 설명 grant_type 필수 client_credentials client_id 필수 앱 등록 시 발급된 systemKey client_secret 필수 앱 등록 시 발급된 secretKey shop_no 필수 앱 실행 시 전달된 쇼핑몰 식별자 partner_no 선택 앱 실행 시 전달된 파트너(공급사) 식별자 - 샵바이 전용
※ 보안상의 이유로 2027.07.01부터 장기 토큰을 사용할 수 없습니다. 장기 토큰을 사용 중이라면 2027.06.30까지 서버 토큰 방식으로 변경해 주시기 바랍니다.
※ 2027.07.01부터 장기 토큰으로 server API 호출이 불가합니다.
- postauthorization code로 장기 토큰 발급하기 (fade-out 예정)
- /auth/token/long-lived
authorization code를 이용해서 장기 access Token(100년)을 발급받습니다
- [특징]
- 외부 서버 등에서 데이터를 주기적으로 동기화하거나 server to server 통신을 위한 토큰입니다.
- 셀러어드민 앱 등록 시 입력한 IP에서만 server API를 호출할 수 있습니다.
- 장기 토큰(access_token)의 유효기간: 100년 (사실상 무기한이며, 별도 refresh_token이 없습니다)
- [이런 경우 장기 토큰을 사용하세요]
- 외부 서버/어드민에서 주기적으로 데이터를 동기화해야 하는 경우
- 쇼핑몰 관리자에 접속하지 않은 상태에서, 서버 간의 주기적인 server API 호출이 필요한 경우
- 단기 토큰을 사용하여 API 호출 시마다 계속 토큰을 갱신하는 것이 적합하지 않은 경우
- [발급 방법 (request body)]
항목명 필수여부 설명 grant_type 필수 authorization_code code 필수 앱 실행 시 발급받은 authorizationCode client_secret 필수 앱 등록 시 발급받은 secretKey redirect_uri 필수 앱 등록 시 입력한 redirectUri client_id 필수 앱 등록 시 발급받은 systemKey
- postauthorization code로 단기 토큰 발급하기
- /auth/token
authorization code를 이용해서 단기 access Token(5분)을 발급받습니다
- [특징]
- server API 통신 시 사용하는 토큰으로, 쇼핑몰 운영자가 쇼핑몰 관리자에 접근해서 앱URI를 실행 시 발급됩니다.
- 셀러어드민 앱 등록 시 입력한 허용된 IP가 아니더라도, 해당 API를 요청한 장비의 IP에서도 server API를 호출할 수 있습니다.
- 토큰 유효기간과 쇼핑몰 관리자 세션 만료 시간(계정 로그인 유지 시간)은 별도이기 때문에 쇼핑몰 관리자를 로그아웃해도 토큰이 유효하다면 server API를 호출할 수 있습니다.
- 토큰의 유효기간(expire_in)이 만료될 경우, 리프레시 토큰을 통해 토큰을 갱신할 수 있습니다.
- [이런 경우 단기 토큰을 사용하세요]
- 외부 서버/관리자가 없거나 혹은 있더라도, 서버 간의 주기적인 동기화를 하지 않고자 하는 경우
- 쇼핑몰 관리자에서 최초 앱 실행 시 단기 토큰으로 일회성으로 인증받은 후 토큰 인증을 추가적으로 계속할 필요가 없는 경우
- [발급 방법 (request body)]
grant_type에 따라, Request body에 입력해야 하는 파라미터가 상이합니다.
최초 발급인 경우 authorizationCode를 통해 발급받을 수 있고, 유효기간이 만료되어 재발급받는 경우 refresh_token을 통해 발급받을 수 있습니다.
단기 토큰의 유효기간은 5분이고, 리프레시 토큰의 유효기간은 24시간입니다.항목명 필수여부 설명 grant_type 필수 authorization_code 또는 refresh_token code 조건부 필수 앱 실행 시 발급받은 authorizationCode
(grant_type이 authorization_code인 경우 입력)refresh_token 조건부 필수 리프레시 토큰
(grant_type이 refresh_token인 경우 입력)client_secret 필수 앱 등록 시 발급받은 secretKey redirect_uri 필수 앱 등록 시 입력한 redirectUri client_id 필수 앱 등록 시 발급받은 systemKey
인증정보 보안 관리
앱이 설치된 쇼핑몰의 토큰을 발급할 때 필요한 인증정보인 systemKey(client_id)와 secretKey(client_secret)는 앱 기준으로 하나만 발급됩니다.
앱에 발급된 인증정보 유출 시 앱을 설치한 모든 쇼핑몰의 데이터 또한 유출될 위험이 있습니다.
데이터 유출 피해를 막기 위해서는 아래의 운영 수칙을 준수해 주시기 바랍니다.
[운영 수칙]
- secretKey는 앱 개발사 서버에만 보관하고, 클라이언트(브라우저·모바일 앱)나 소스 저장소에 포함하지 않습니다.
- 로그와 에러 메시지에 토큰과 secretKey 값을 남기지 않습니다.
- 앱에는 server API 호출 시 사용하는 IP만 등록하고, 사용하지 않는 IP는 등록하지 않습니다.
만약 특정 쇼핑몰의 토큰 유출이 의심되는 경우 NHN 커머스 1:1 문의를 통해 이를 알려 토큰을 차단해 주시기 바랍니다. 토큰이 차단된 쇼핑몰은 더 이상 토큰을 발급할 수 없으며, 이전에 발급된 토큰은 폐기됩니다.