> For the complete documentation index, see [llms.txt](https://toss-ads.gitbook.io/toss-ads/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://toss-ads.gitbook.io/toss-ads/getting-started/authentication.md).

# 인증하기

Access Token은 토스애즈 API를 호출할 때 필요해요. 이 문서에서는 토큰을 발급받는 방법과 API 호출에 쓰는 방법을 알려드려요.

## 시작하기 전에

광고주센터에서 **API 키(Client ID와 Client Secret)**를 먼저 발급받아 주세요.

* 발급 위치: [광고주센터](https://ads-platform.toss.im/advertiser/api-key) > 광고도구 > API 키
* API 키는 계정장만 발급할 수 있어요.
* Client Secret은 발급할 때 한 번만 확인할 수 있어요. 발급받은 즉시 따로 저장해 주세요.
* Client Secret이 클라이언트 코드나 공개 저장소에 노출되지 않도록 주의해 주세요. 

## 1. Access Token 발급받기

광고주센터에서 발급받은 Client ID와 Client Secret으로 Access Token을 요청해요.

API를 호출하려면 그 API에 필요한 권한이 Access Token에 담겨 있어야 해요. 권한은 발급받을 때 `scope`에 넣어요. 예를 들어 Reporting API를 호출하려면 `scope`에 `ads:report.read`를 넣어 Access Token을 발급받아야 해요.

* **POST** `https://oauth2.cert.toss.im/token`

```jsx
curl -X POST https://oauth2.cert.toss.im/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Accept: application/json; charset=UTF-8" \
    -d "grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope={scope}"
```

`-d` 뒤에 오는 값이 요청 본문이에요. 필드를 `&`로 이어 붙인 형식이에요. 중괄호(`{ }`)로 표시한 자리에 아래 값을 넣어 주세요.

<table><thead><tr><th width="155.22222900390625">필드</th><th width="102.33331298828125">타입</th><th width="92.77777099609375">필수</th><th>설명</th></tr></thead><tbody><tr><td><code>grant_type</code></td><td>string</td><td>O</td><td>토큰을 발급받는 방식(OAuth2 grant type)이에요. 항상 <code>client_credentials</code>를 넣어 주세요.</td></tr><tr><td><code>client_id</code></td><td>string</td><td>O</td><td>광고주센터에서 발급받은 Client ID예요.</td></tr><tr><td><code>client_secret</code></td><td>string</td><td>O</td><td>광고주센터에서 발급받은 Client Secret이에요.</td></tr><tr><td><code>scope</code></td><td>string</td><td>O</td><td><p>요청할 권한 범위예요. 호출할 API에 필요한 권한을 넣어 주세요.</p><p>여러 개를 요청하려면 공백으로 구분해 주세요.<br>예: <code>ads:report.read ads:report.write</code></p></td></tr></tbody></table>

발급에 성공하면 아래와 같은 응답을 받아요.

```jsx
{
	"access_token": "{발급된 access token}",
	"scope": "ads:report.read",
	"token_type": "Bearer",
	"expires_in": 31535999
}
```

<table><thead><tr><th width="171.11109924316406">필드</th><th width="175.88888549804688">타입</th><th>설명</th></tr></thead><tbody><tr><td><code>access_token</code></td><td>string</td><td>발급된 Access Token이에요. API를 호출할 때 사용해요.</td></tr><tr><td><code>scope</code></td><td>string</td><td>요청한 권한 범위예요.</td></tr><tr><td><code>token_type</code></td><td>string</td><td>토큰 타입이에요.</td></tr><tr><td><code>expires_in</code></td><td>integer</td><td>토큰의 유효 기간이에요. 초 단위예요.</td></tr></tbody></table>

### 토큰을 다룰 때 알아두세요

* Access Token이 클라이언트 코드나 공개 저장소에 노출되지 않도록 주의해 주세요.
* 발급받은 토큰은 저장해 두고 만료 전까지 재사용해 주세요. API를 호출할 때마다 새로 발급받으면 재발급 요청이 많아져 이용이 제한될 수 있어요.
* `expires_in` 값(초 단위)을 확인하고, 만료되기 전에 새로 발급받는 걸 권장해요.
* 만료된 토큰으로 호출하면 `401` 에러가 발생해요. 이 경우 토큰을 재발급받은 뒤 다시 호출해 주세요.

## 2. API 호출에 토큰 넣기

토스애즈의 모든 API는 [Bearer 인증](https://docs.tosspayments.com/resources/glossary/bearer-auth)을 사용해요. API를 호출할 때는 모든 요청의 `Authorization` 헤더에 발급받은 Access Token을 아래 형식으로 넣어 주세요.

`Authorization: Bearer {발급된 access token}`&#x20;

예를 들어 Reporting API에서 지표 목록을 조회하려면 이렇게 호출해요.

```jsx
curl --request GET 'https://tossads-api.toss.im/v1/reports/metrics' \
--header 'Authorization: Bearer {발급된 access token}'
```

광고 성과를 조회하는 더 자세한 방법은 [Reporting](/toss-ads/references/reporting.md) 가이드에서 확인해 주세요.


---

# 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://toss-ads.gitbook.io/toss-ads/getting-started/authentication.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.