---
title: "API 인증: CheckoutOS 문서 | Chargezen"
description: "CheckoutOS API에 안전하게 접근해요. Chargezen CheckoutOS 문서의 API 참조 섹션에 있어요."
url: "https://chargezen.com/ko/docs/checkoutos/api/authentication"
lang: "ko"
updated: "2025-01-16"
---

Canonical URL: https://chargezen.com/ko/docs/checkoutos/api/authentication

# API 인증

CheckoutOS API에 안전하게 접근해요

마지막 업데이트: 2025-01-16

CheckoutOS API는 API 키로 인증해요. 이 가이드에서는 키 생성, 요청 인증, API 접근을 안전하게 관리하는 방법을 설명해요.

## API 키

API 키는 CheckoutOS API의 모든 요청을 인증하는 데 사용해요. 각 키는 스토어에 연결되며 권한을 설정할 수 있어요.

### API 키 생성

1

#### 설정으로 이동

CheckoutOS → Settings → API로 이동하세요.

2

#### 새 키 만들기

"Create API Key"를 클릭하세요.

3

#### 키 이름 지정

"프로덕션 서버"처럼 설명이 담긴 이름을 지정하세요.

4

#### 권한 설정

키가 접근할 수 있는 API 범위를 선택하세요.

5

#### 키 복사

키는 다시 표시되지 않으므로 즉시 복사하세요.

키 보안

API 키는 생성할 때 한 번만 표시돼요. 안전하게 보관하세요. 분실하면 새 키를 생성해야 해요.

## 인증 방식

### Bearer 토큰(권장)

Authorization 헤더에 API 키를 Bearer 토큰으로 포함하세요.

Bearer 토큰 인증

```bash
curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### X-API-Key 헤더

대신 X-API-Key 헤더를 사용할 수도 있어요.

X-API-Key 인증

```bash
curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## API 권한

API 키의 범위를 특정 권한으로 제한할 수 있어요.

사용 가능한 범위

```json
{
  "scopes": {
    "read:upsells": "View upsell configurations",
    "write:upsells": "Create and modify upsells",
    "read:bundles": "View bundle configurations",
    "write:bundles": "Create and modify bundles",
    "read:analytics": "Access analytics data",
    "read:orders": "View order data",
    "write:orders": "Modify orders (edits)",
    "read:settings": "View CheckoutOS settings",
    "write:settings": "Modify settings",
    "webhooks:manage": "Create and manage webhooks"
  }
}
```

최소 권한

연동에 필요한 권한만 부여하세요. 분석 대시보드용 키에는 추가 판매를 수정할 권한이 없어야 해요.

## 요청 속도 제한

공정한 사용을 위해 API 요청 횟수를 제한해요.

요청 한도

```json
{
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 3600,
    "burst_limit": 20
  },
  "headers": {
    "X-RateLimit-Limit": "120",
    "X-RateLimit-Remaining": "115",
    "X-RateLimit-Reset": "1640000000"
  }
}
```

요청 한도에 도달하면 429 응답을 받아요.

요청 한도 응답

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}
```

## 환경

CheckoutOS는 개발 환경과 프로덕션 환경을 별도로 제공해요.

API 환경

```json
{
  "production": {
    "base_url": "https://api.chargezen.com/v1",
    "key_prefix": "live_"
  },
  "sandbox": {
    "base_url": "https://sandbox.api.chargezen.com/v1",
    "key_prefix": "test_"
  }
}
```

샌드박스 환경

개발과 테스트에는 샌드박스를 사용하세요. 샌드박스 데이터는 프로덕션과 분리되며 언제든 초기화할 수 있어요.

## 공식 SDK

공식 SDK는 인증을 자동으로 처리해요.

Node.js SDK

```javascript
import { CheckoutOS } from '@chargezen/checkoutos-sdk';

const client = new CheckoutOS({
  apiKey: process.env.CHARGEZEN_API_KEY,
  environment: 'production'
});

const upsells = await client.upsells.list();
```

Python SDK

```python
from chargezen import CheckoutOS

client = CheckoutOS(
    api_key=os.environ['CHARGEZEN_API_KEY'],
    environment='production'
)

upsells = client.upsells.list()
```

## 키 관리

#### 권장 방법

*   환경 변수 사용 — 키를 코드에 직접 넣지 마세요
*   정기적인 키 교체 — 최소 분기마다 교체하세요
*   환경별로 별도 키 사용 — 개발, 스테이징, 프로덕션을 구분하세요
*   사용하지 않는 키 폐기 — 더 이상 사용하지 않는 키를 삭제하세요
*   키 사용 모니터링 — 비정상적인 패턴을 관찰하세요
*   최소 범위 사용 — 필요한 권한만 부여하세요

## 키 폐기

1

#### API 설정으로 이동

CheckoutOS → Settings → API로 이동하세요.

2

#### 키 찾기

목록에서 폐기할 키를 찾으세요.

3

#### 폐기

"Revoke"를 클릭하고 확인하세요.

즉시 적용

키 폐기는 즉시 적용돼요. 폐기된 키를 사용하는 모든 요청은 실패해요. 폐기하기 전에 애플리케이션을 업데이트했는지 확인하세요.

## API 참조

[

### API 엔드포인트

사용 가능한 API 엔드포인트

자세히 보기



](https://chargezen.com/ko/docs/checkoutos/api/endpoints)[

### 웹훅

실시간 이벤트 알림

자세히 보기



](https://chargezen.com/ko/docs/checkoutos/api/webhooks)

이 페이지가 도움이 되었나요?

도움이 더 필요하신가요? [고객 지원 문의](https://chargezen.com/ko/docs/checkoutos/troubleshooting/support)