---
title: "API 키"
description: "API 요청을 인증하고 키를 안전하게 보관하세요."
source: "https://docs.tokenz.one/ko-KR/v2/checkout/api-keys"
api_version: "v2"
locale: "ko-KR"
version_status: "current"
docs_stage: "prod"
---

# API 키

API 요청을 인증하고 키를 안전하게 보관하세요.

## 소개

모든 Tokenz API v2 요청은 Bearer 토큰으로 전송하는 **비밀 API 키**로 인증합니다.

```bash
curl https://api.tokenz.one/v2/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'
```

Tokenz API v2에서는 **비밀 키만** 사용하며, 공개용 또는 클라이언트용 키는 사용되지 않습니다. 비밀 키는 계정의 결제를 생성하고 주문 데이터를 읽을 수 있으므로 **절대로 서버 외부로 노출하면 안 됩니다.**

대시보드의 **Developers → API keys**에서 키를 생성하고 관리합니다.

## 테스트 키와 라이브 키

각 키는 하나의 모드에 속합니다.

| 접두사 | 모드 | 실제 결제 |
| --- | --- | --- |
| `secret_test_…` | 테스트 | 없음 — 모의 결제만 수행 |
| `secret_live_…` | 라이브 | 있음 — 실제 결제 |

개발 및 테스트에는 **테스트** 키를 사용하고 실제 결제를 받으려면 **라이브** 키로 전환하세요. 테스트 키는 실제 결제를 처리할 수 없고 라이브 키는 테스트 모드에 사용할 수 없습니다. 환경별로 분리하여 설정하세요(예: 환경마다 다른 `TOKENZ_SECRET_KEY` 변수).

## 비밀 키 보호

클라이언트에서 안전하게 사용할 수 있는 키가 없으므로 비밀번호처럼 취급하세요.

- **서버에서만 사용하세요.** 브라우저 코드, 모바일 앱, SPA 번들 등 사용자 기기에 배포되는 곳에 넣지 마세요.
- 버전 관리 저장소에 **커밋하지 말고**, 로그, 오류 메시지, URL에도 포함하지 마세요.
- 코드가 아닌 **환경 변수나 비밀 정보 관리자에 저장하세요.**

> 키는 생성할 때 **한 번만** 표시됩니다. 즉시 복사해 안전하게 보관하세요. 잃어버렸다면 복구를 시도하지 말고 새 키를 생성하세요.

## 필요한 권한 범위만 부여

키 생성 시 Checkout Session 생성·조회, 주문 조회·취소, 아이템 지급 기록, 상품 조회, 환불 생성·조회, 코드 검증·사용, 구독 요금제 변경 등의 **권한 범위(scopes)**를 선택합니다.

키마다 필요한 **최소 권한**만 부여하세요.

- **연동 또는 서비스별로 별도 키**를 만들고 사용하는 권한만 부여하세요. 주문 조회만 하는 보고 작업에는 환불이나 Checkout 권한이 필요하지 않습니다.
- 제한된 키가 유출되면 피해 범위를 줄일 수 있고, 다른 기능에 영향을 주지 않고 해당 키만 폐기할 수 있습니다.

## 키 교체 및 폐기

- **교체**: 새 키를 생성해 배포한 후 **Developers → API keys**에서 기존 키를 삭제하세요. 여러 키를 동시에 보유할 수 있어 중단 없이 교체할 수 있습니다.
- 저장소 커밋, 티켓 붙여넣기, 로그 기록 등으로 **노출되었다면** 즉시 삭제하세요. 삭제하면 폐기되어 해당 키를 쓰는 모든 요청이 중단됩니다. 그 후 대체 키를 발급하세요.

## 웹훅 서명 비밀키

웹훅 엔드포인트의 **서명 비밀키**는 API 키와 별개입니다. Tokenz가 이를 사용해 서명하며, 판매자는 **원본 요청 본문**으로 `Tokenz-Signature` 헤더를 검증하여 진위를 확인합니다. API 키처럼 서버에만 보관하세요.

서명 검증 방법은 [웹훅](https://docs.tokenz.one/ko-KR/v2/checkout/webhooks-get-started)을 참고하세요.