> For the complete documentation index, see [llms.txt](https://workspace-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workspace-help.nhn-commerce.com/contents/recommended/access_token.md).

# \[셀러어드민-앱] 장기 토큰에서 서버 토큰으로 전환하기

사용 중인 장기 토큰을 서버 토큰으로 어떻게 전환해야 하는지 전환 방법을 안내하는 콘텐츠입니다.

{% hint style="warning" %}
2026.10.29 이후 등록된 앱은 장기 토큰 발급이 불가합니다. \
기존 **장기 토큰을 발급한 사용자는 2027.06.30 까지 서버 토큰으로 전환**해야 하며, \
**2027.07.01 부터 장기 토큰으로 server API 호출이 불가**합니다.
{% endhint %}

## 조치 대상

2026.10.29 이전에 쇼핑몰 설치형 앱으로 등록된 앱은 모두 전환 대상에 포함됩니다.

셀러어드민 > 상품 > 앱 화면에서 앱 정보에 **\[조치 필요]** 태그가 표시된다면 전환 대상입니다.

## 필독사항

* \[조치 완료] 처리 후에는 기존 장기 토큰이 모두 폐기되어 복원할 수 없으며, 장기 토큰도 더 이상 발급할 수 없습니다.
* \[조치 완료]는 조치 절차를 모두 확인하고, 정보 수집과 코드 변경을 마친 뒤에 처리해야 합니다.
* 서버 토큰은 \[조치 완료] 이후에만 발급할 수 있습니다.
* \[조치 완료] 후 서버 토큰을 발급받기 전까지는 서버 토큰 발급하기 API 외의 다른 server API를 호출할 수 없습니다.
* 서버 토큰은 어드민 기준으로 쇼핑몰당 하나만 발급할 수 있습니다. 새로 발급하면 이전 서버 토큰은 폐기되며, 폐기된 토큰으로는 server API를 호출할 수 없습니다.
* 앱 개발 가이드의 인증정보 보안 관리 내용에 포함된 운영 수칙을 준수해야 합니다.

## 조치 절차

전환 대상이더라도 장기 토큰 이용 여부에 따라 조치 방법이 다릅니다.

📍조치 경로: 셀러어드민 > 상품 > 앱 화면

<figure><img src="https://67612295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLt0GowPleXLWRjzGIAiV%2Fuploads%2F3a3Yd6liyNwcDzS9Pir7%2F11.png?alt=media&amp;token=66e1e428-b6ca-4ad7-981d-a0ffc274f5f4" alt=""><figcaption></figcaption></figure>

① 장기 토큰을 발급하거나 이용하지 않는 경우

별도 작업 없이 즉시 \[조치 완료] 처리해 주세요.

② 장기 토큰을 발급해 이용 중인 경우

아래 순서로 조치한 뒤 \[조치 완료] 처리해 주세요.

실제 서비스 중인 앱에 바로 적용하기보다 개발용 앱이나 자체 테스트 환경에서 충분히 테스트한뒤 적용하기를 권장합니다.

**A. 정보 수집 (보유한 장기 토큰마다 반복)**

1\. 보유 중인 장기 토큰으로 몰 정보 조회하기(`GET/auth/me`) API를 호출해 주세요.

샵바이: [몰 정보 조회하기 API >](https://server-docs.shopby.co.kr/?url.primaryName=workspace/#/Auth/get-mall-profile)

고도몰: [몰 정보 조회하기 API >](https://server-docs.godomall.com/?activeName=%EC%9D%B8%EC%A6%9D#/Auth/get-mall-profile)

2\. 응답된 mall.shopNo와 partner.partnerNo를 저장해 주세요. (partner.partnerNo가 null이면 mall.shopNo만 저장)

※ \[조치 완료] 시 모든 장기 토큰이 폐기되어 이 API를 호출할 수 없으므로, 보유한 모든 장기 토큰에 대해 A를 먼저 끝내 주세요.

{% hint style="info" %}
partner.partnerNo 값은 샵바이 전용입니다. 고도몰 공급사에는 앱 서비스가 지원되지 않습니다.
{% endhint %}

**B. 앱 변경 및 조치 완료 (앱당 1회)**

3\. 앱 소스코드에서 장기 토큰 발급하기(`POST /auth/token/long-lived`)를 호출하는 곳을 모두 서버 토큰 발급하기(`POST /oauth/token`)로 변경하고, 변경한 코드를 미리 배포해 주세요.

샵바이: [서버 토큰 발급하기 API >](https://server-docs.shopby.co.kr/?url.primaryName=workspace/#/Auth/create-server-token)

고도몰: [서버 토큰 발급하기 API >](https://server-docs.godomall.com/?activeName=%EC%9D%B8%EC%A6%9D#/Auth/create-server-token)

4\. 셀러어드민 > 상품 > 앱 화면의 \[조치 필요] 태그로 조치 필요사항 팝업을 열어 \[조치 완료] 처리해 주세요.

{% hint style="danger" %}
\[조치 완료] 직후부터 서버 토큰을 발급 받을 때까지 server API를 호출할 수 없습니다. 트래픽이 적은 시간에 진행하고, \[조치 완료] 직후 바로 서버 토큰을 발급 받을 수 있도록 준비해 주세요.
{% endhint %}

**C. 서버 토큰 적용 (수집한 정보만큼 반복)**

5\. 저장해 둔 shopNo, partnerNo를 shop\_no, partner\_no로 전달하고, grant\_type(client\_credentials), client\_id, client\_secret과 함께 서버 토큰 발급하기 API를 호출해 주세요.

6\. 발급된 서버 토큰(유효기간 24시간)을 저장해 주세요.

7\. 저장된 서버 토큰으로 server API를 호출해 주세요. 24시간이 지나 만료되면 (5)와 같은 방법으로 다시 발급해 주세요.

## 서버 토큰 발급 에러 코드

서버 토큰 발급에 실패하면 아래 에러 코드를 확인해 주세요.

| 상태 코드 | 에러 코드  | 에러 메시지                                    | 대처 방                                               |
| ----- | ------ | ----------------------------------------- | -------------------------------------------------- |
| 400   | A0020  | grant\_type 값이 올바르지 않습니다.                 | grant\_type 값을 client\_credentials로 보냈는지 확인해 주세요.  |
| 400   | E1001  | 이미 처리된 요청입니다.                             | 같은 요청이 중복으로 전송되지 않았는지 확인해 주세요.                     |
| 400   | PE0001 | 존재하지 않거나, 쇼핑몰과 계약되지 않은 파트너입니다.            | partner\_no 값이 올바른지 확인해 주세요.                       |
| 401   | A0018  | client\_id 와 client\_secret 값이 올바르지 않습니다. | client\_id, client\_secret이 앱에 발급된 값과 같은지 확인해 주세요. |
| 403   | A0022  | 서버 토큰을 발급할 수 없는 앱입니다.                     | 셀러어드민 > 상품 > 앱 화면에서 \[조치 완료] 처리를 했는지 확인해 주세요.      |
| 403   | AP0004 | 존재하지 않거나, 앱이 설치되지 않은 쇼핑몰입니다.              | shop\_no 값이 올바른지, 해당 쇼핑몰에 앱이 설치되어 있는지 확인해 주세요.     |
| 403   | S0001  | server API 호출 불가한 IP 주소입니다.               | 발급을 요청하는 서버의 IP가 앱에 등록되어 있는지 확인해 주세요.              |
| 403   | A0019  | 보안상의 이유로 토큰 발급이 차단된 쇼핑몰입니다.               | NHN 커머스 1:1 문의를 통해 차단 해제를 요청해 주세요.                 |
| 500   | 99999  | 토큰 발급에 실패했습니다. 잠시 후 다시 시도해 주세요.           | 잠시 후 다시 시도하고, 계속되면 NHN 커머스 1:1 문의로 알려 주세요.         |

## FAQ

{% prompt description="전환하지 않으면 어떻게 되나요?" icon="q" openInAIProviders="false" defaultExpanded="hidden" %}

```markdown
2027.06.30 이후에는 장기 토큰으로 server API를 호출할 수 없어, 해당 API를 사용하는 기능이 동작하지 않습니다.
```

{% endprompt %}

{% prompt description="단기 토큰만 쓰는데 해야 하나요?" icon="q" openInAIProviders="false" %}

```markdown
전환 작업은 필요 없습니다. 셀러어드민에서 [조치 완료]만 처리해 주세요.
```

{% endprompt %}

{% prompt description="쇼핑몰이 여러 개인데 어떻게 하나요?" icon="q" openInAIProviders="false" %}

```markdown
장기 토큰은 쇼핑몰별로 발급되므로 A와 C는 쇼핑몰마다 반복하고, B(코드 변경, [조치 완료])는 앱당 한 번만 하면 됩니다.
```

{% endprompt %}

{% prompt description="partnerNo가 null로 내려와요." icon="q" openInAIProviders="false" %}

```markdown
shopNo만 저장해서 서버 토큰을 발급하면 됩니다. partner_no는 샵바이 전용이며, 파트너(공급사) 관리자에서 앱을 실행한 경우에만 전달됩니다.
```

{% endprompt %}

{% prompt description="서버 토큰이 만료되면 어떻게 하나요?" icon="q" openInAIProviders="false" %}

```markdown
유효기간은 24시간이며, 만료되면 최초 발급과 같은 방법으로 다시 발급합니다.
```

{% endprompt %}
