> For the complete documentation index, see [llms.txt](https://sharelink-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sharelink-docs.toss.im/developers/open-api/auth.md).

# 연동 시작하기

연동 전에 한 번만 준비하는 것들입니다. 사용 승인, 인증 정보 발급, 출발지 IP 등록, 주문 이벤트 수신 URL 등록을 다룹니다.

셀러용 Open API와 쉐어링크 Open API의 인증 정보는 별개입니다. 셀러용 clientId에 sharelink 스코프를 지정해도 쉐어링크용 인증 정보가 되지 않습니다. 쉐어링크 연동에는 쉐어링크 크리에이터 어드민의 연동 → API 키 발급에서 확인한 Access Key / Secret Key를 사용해 주세요. 여기서 Access Key는 `client_id`, Secret Key는 `client_secret`에 해당합니다.

API로 받은 상품 정보를 캐시해 추천 페이지에 일부 상품만 보여주어도 해당 서비스 사용이 자동으로 승인되는 것은 아닙니다. 저장 기간과 노출 상품 수만으로 승인 여부를 판단할 수 없습니다. 서비스 사용 승인, 데이터 갱신 기준, 상품 이미지 사용 범위를 각각 확인해 주세요. 개별 사용 범위를 확인하려면 서비스 URL·노출 화면·저장 기간·이미지 사용 방식을 준비해 [토스쇼핑 고객센터](https://toss-business.channel.io)에 문의해 주세요.

사용 승인 신청부터 인증 정보 발급까지 모두 쉐어링크 크리에이터 어드민에서 하는 작업이며, 코드로 호출하는 부분은 없습니다.

준비가 끝나면 빠른 시작에서 실제로 호출해 보시면 됩니다.

***

## 환경과 Base URL

| 환경 | Base URL                            |
| -- | ----------------------------------- |
| 운영 | `https://sharelink.toss.im/openapi` |

Open API는 **운영 환경에서만 제공**됩니다. 별도의 테스트(알파) 환경은 없으므로, 연동 검증도 운영 환경에서 진행해 주세요.

전송 구간은 **TLS 1.2 이상 HTTPS만** 허용합니다.

***

## 1. 사용 승인 받기

{% hint style="warning" %}
**현재 신규 사용 신청을 잠시 받지 않습니다.** 외부 웹사이트에 상품 가격이 노출되는 문제와 관련해 운영 기준을 정비하는 중입니다. 반려된 뒤 다시 신청하시는 것도 지금은 할 수 없습니다. 이미 승인받으신 사업자는 아래 2번부터 그대로 진행하시면 됩니다.
{% endhint %}

쉐어링크 Open API는 **승인제**로 운영됩니다. 사용 신청 후 검수를 거쳐 **승인받은 사업자(정산 거래처)만** 인증 정보를 발급받으실 수 있습니다. 승인 전에는 인증 정보 발급이 거절됩니다.

| 항목    | 내용                                                  |
| ----- | --------------------------------------------------- |
| 신청 방법 | 현재 신규 신청을 잠시 받지 않습니다                                |
| 결과 안내 | 승인·반려 모두 이메일과 알림톡으로 알려 드립니다. 반려 시에는 사유를 함께 안내해 드립니다 |
| 재신청   | 현재 반려 후 재신청도 잠시 받지 않습니다                             |
| 승인 유지 | 승인 후 인증 정보를 바로 발급하지 않으셔도 승인이 만료되지 않습니다              |

> **어떤 서비스가 승인되나요?** 스레드·인스타그램 같은 SNS, 오픈채팅방, 카페, 블로그, 그리고 이런 채널의 게시를 자동화해 주는 플랫폼 서비스는 허용됩니다. 캐시백·리워드 앱, 포인트 적립형 앱처럼 사용자에게 쉐어링크를 제공하고 주문 이벤트로 구매·취소를 확인해 리워드를 지급하는 **앱·리워드 서비스도 허용됩니다.** 반면 API로 받은 상품 가격을 데이터베이스에 쌓아 두고 이커머스 사이트처럼 나열·전시하거나 다른 플랫폼과 가격을 비교해 보여주는 **커머스형 웹사이트는 승인되지 않습니다.**

> **주문 이벤트만 연동하셔도 되나요?** 네. 상품 조회 API를 쓰지 않고 주문 이벤트 수신·주문 이벤트 조회만 연동하시는 경우에도 같은 승인 절차를 따릅니다. 별도 신청 경로는 없습니다.

***

## 2. 인증 정보 발급

승인이 완료되면 쉐어링크 크리에이터 어드민(`sharelink.toss.im`)의 **연동 → API 키 발급** 메뉴에서 직접 발급받으실 수 있습니다.

**Access Key** / **Secret Key** 한 쌍이 발급됩니다. OAuth 규격의 `client_id` / `client_secret`과 같은 것이며, 빠른 시작 예제에서 이 한 쌍으로 액세스 토큰을 받습니다.

> 발급받으신 Access Key / Secret Key는 이후에도 어드민의 **연동 → API 키 발급** 메뉴에서 **다시 확인하실 수 있습니다.** 값을 따로 적어 두지 않았더라도 재발급 대신 어드민 조회로 확인해 주세요. 같은 화면에 링크 발급에 쓰는 **회원 연동 ID**(퍼블리셔 UUID, `publisherId`)도 표시됩니다.

인증 정보 폐기와 Secret Key 재발급은 토스 운영자만 수행합니다. Secret Key가 외부에 노출된 것 같다면 [토스쇼핑 고객센터](https://toss-business.channel.io)로 문의해 주세요. 토스 운영자가 Secret Key를 재발급해 드립니다. Access Key는 그대로 유지되지만 **기존 Secret Key는 재발급 즉시 사용할 수 없으므로**, 연동 시스템의 키 교체 시점은 고객센터 안내에 따라 조율해 주세요.

> 인증 정보는 **사업자(정산 거래처) 단위로 1개**가 발급됩니다. 같은 사업자에 소속된 계정이 여럿이어도 동일한 키를 공유하며, Secret Key가 재발급되면 다른 계정이 쓰던 기존 키도 함께 무효가 됩니다.

### 스코프

발급 시 아래 두 스코프가 기본으로 부여됩니다. 토큰이 무엇을 할 수 있는지를 정하는 값입니다.

| 스코프               | 용도                                                    |
| ----------------- | ----------------------------------------------------- |
| `sharelink:read`  | **조회.** 카테고리·상품 목록·상품 상세·subTag 목록·실적·정산 실적·주문 이벤트 조회 |
| `sharelink:write` | **변경.** 쉐어링크 발급, subTag 등록·수정·삭제                      |

**서버 상태를 바꾸지 않는 호출은 `sharelink:read`, 바꾸는 호출은 `sharelink:write`가 필요합니다.** 앞으로 추가되는 기능도 이 기준을 따르므로, 엔드포인트별 스코프는 각 API 문서 상단에서 확인해 주세요. (연결성 확인과 주문 이벤트 수신(Push)은 스코프를 쓰지 않습니다.)

토큰을 받을 때 필요한 스코프를 지정하게 되는데, 구체적인 방법은 빠른 시작의 1단계에 있습니다.

***

## 3. 출발지 IP 등록

API를 호출하는 서버의 고정 출발지 IP를 등록하셔야 호출이 허용됩니다. 2번의 발급 화면에서 함께 등록하시면 됩니다.

| 항목    | 내용                                                           |
| ----- | ------------------------------------------------------------ |
| 등록 방법 | 쉐어링크 크리에이터 어드민에서 직접 등록·수정                                    |
| 등록 개수 | 사업자당 최대 10개                                                  |
| 표기    | 단일 IPv4 주소(예: `203.0.113.10`) 또는 IP 대역(예: `160.79.104.0/21`) |

> **IP 대역은 `/16`부터 `/32`까지 등록하실 수 있습니다.** 대역으로 등록하시면 그 안의 IP 전체가 허용되므로, 출발지가 여러 개인 경우 한 줄로 등록하실 수 있습니다. 대역 하나도 등록 개수 1개로 셉니다. 더 넓은 대역이 필요하면 [토스쇼핑 고객센터](https://toss-business.channel.io)로 문의해 주세요.
>
> **대역은 시작 주소로 적어 주세요.** `160.79.104.0/21`은 등록되지만 `160.79.104.5/21`은 등록되지 않습니다. 이 경우 어떤 값으로 적어야 하는지 화면에서 안내해 드립니다.

> **등록할 IP는 내 PC가 아니라 API를 호출하는 서버의 IP입니다.** 등록된 IP가 하나도 없으면 모든 호출이 차단됩니다.

서버 증설·이전 등으로 출발지 IP가 바뀌는 경우, 미리 어드민에서 추가 등록해 주세요.

***

## 4. 주문 이벤트 수신 URL 등록 (선택)

구매·취소·구매확정 이벤트를 제휴사 서버로 받으시려면(캐시백·리워드 연동) 제휴사가 준비한 **HTTPS 수신 URL**을 2번의 API 연동 화면 아래 **주문 이벤트 수신** 카드에서 등록하고 수신을 켭니다. 수신 URL은 최대 3개까지 등록할 수 있습니다.

URL 규칙, 토스 발신 IP, 서명 검증 방법은 주문 이벤트 수신 (Push)에 있습니다. 위 3번의 출발지 IP(제휴사 → 토스)와 방향이 반대인 점에 주의해 주세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://sharelink-docs.toss.im/developers/open-api/auth.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.