인증 (API Key)
API Key를 사용하여 SweetBook API에 인증하는 방법을 설명합니다.
개요
SweetBook API는 API Key 기반 Bearer Token 인증을 사용합니다. 모든 API 요청에 Authorization 헤더를 포함해야 합니다.
text
Authorization: Bearer {YOUR_API_KEY}API Key 특징
- SB 접두사: 모든 API Key는
SB로 시작하며.을 포함합니다 - 환경 구분: Sandbox 키와 Live 키가 분리되어 있습니다
- IP 제한: 선택적으로 허용 IP를 설정하여 보안을 강화할 수 있습니다
- 만료 없음: API Key는 폐기하지 않는 한 계속 유효합니다
API Key 발급
API Key는 파트너 포털에서 발급받을 수 있습니다.
- 파트너 포털에 로그인합니다
- 설정 > API Key 메뉴로 이동합니다
- 새 API Key 발급 버튼을 클릭합니다
- 환경(Sandbox/Live)을 선택합니다
- 발급된 API Key를 안전하게 저장합니다
API Key는 발급 시에만 전체 값을 확인할 수 있습니다. 발급 후에는 접두사(prefix)만 표시되므로, 발급 즉시 안전한 곳에 저장하세요.
환경별 API Key
| 환경 | 용도 | 과금 |
|---|---|---|
sandbox | 개발 및 테스트 환경 | 테스트 충전금 사용 (무료) |
live | 프로덕션 환경 (사업 협의 후 사용 가능) | 실제 충전금 차감 |
Sandbox 환경
Sandbox 환경은 실제 과금 없이 API를 테스트할 수 있는 환경입니다. 환경에 따라 API Base URL이 다르며, 서버는 요청 도메인을 기반으로 자동으로 환경을 판별합니다.
API Base URL
| 환경 | Base URL |
|---|---|
| Live | https://api.sweetbook.com/v1 |
| Sandbox | https://api-sandbox.sweetbook.com/v1 |
도메인 기반 환경 분기
서버는 요청 도메인을 기반으로 환경을 자동으로 판별합니다. 별도의 isTest 쿼리 파라미터가 필요하지 않습니다.
- Sandbox(test) 환경: 도메인에
sandbox가 포함되거나,localhost,127.0.0.1인 경우 - Live 환경: 위 조건에 해당하지 않는 모든 도메인
Sandbox 키 사용 예시
bash
curl -X GET 'https://api-sandbox.sweetbook.com/v1/books' \
-H "Authorization: Bearer SBxxxxxxxx.xxxxxxxxxxxxxxxx"Sandbox API Key는 반드시 sandbox 도메인으로 호출해야 합니다. Live 도메인으로 호출하면 환경 불일치 에러가 발생합니다.
API 호출
아래 예시는 Live 환경 기준입니다. Sandbox 테스트 시에는 Base URL을 https://api-sandbox.sweetbook.com/v1로 변경하세요.
curl
bash
# Live 환경
curl -X GET 'https://api.sweetbook.com/v1/books' \
-H "Authorization: Bearer SBxxxxxxxx.xxxxxxxxxxxxxxxx"
# Sandbox 환경
curl -X GET 'https://api-sandbox.sweetbook.com/v1/books' \
-H "Authorization: Bearer SBxxxxxxxx.xxxxxxxxxxxxxxxx"JavaScript (fetch)
javascript
const API_KEY = 'SBxxxxxxxx.xxxxxxxxxxxxxxxx';
// Sandbox 테스트 시: 'https://api-sandbox.sweetbook.com/v1'
const BASE_URL = 'https://api.sweetbook.com/v1';
const response = await fetch(`${BASE_URL}/books`, {
headers: {
'Authorization': `Bearer ${API_KEY}`
}
});
const data = await response.json();
console.log(data);
// {
// "success": true,
// "data": [ ... ],
// "message": "Success"
// }JavaScript (axios)
javascript
import axios from 'axios';
// Sandbox 테스트 시 baseURL을 'https://api-sandbox.sweetbook.com/v1'로 변경
const api = axios.create({
baseURL: 'https://api.sweetbook.com/v1',
headers: {
'Authorization': 'Bearer SBxxxxxxxx.xxxxxxxxxxxxxxxx'
}
});
// 책 목록 조회
const { data } = await api.get('/books');
console.log(data);Python (requests)
python
import requests
API_KEY = 'SBxxxxxxxx.xxxxxxxxxxxxxxxx'
# Sandbox 테스트 시: 'https://api-sandbox.sweetbook.com/v1'
BASE_URL = 'https://api.sweetbook.com/v1'
headers = {
'Authorization': f'Bearer {API_KEY}'
}
response = requests.get(f'{BASE_URL}/books', headers=headers)
data = response.json()
print(data)인증 에러
| 상태 코드 | 의미 | 원인 |
|---|---|---|
| 401 Unauthorized | 인증 실패 | API Key가 없거나 잘못된 형식 |
| 403 Forbidden | 접근 거부 | API Key가 폐기되었거나, IP 제한에 의해 차단됨 |
| 429 Too Many Requests | 요청 제한 초과 | 단시간에 너무 많은 요청을 전송함 |
에러 응답 예시
json
{
"success": false,
"message": "Unauthorized",
"data": null,
"errors": ["유효하지 않은 API Key입니다."]
}에러 처리 예시
javascript
const response = await fetch('https://api.sweetbook.com/v1/books', {
headers: {
'Authorization': `Bearer ${API_KEY}`
}
});
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 401:
console.error('API Key가 유효하지 않습니다.');
break;
case 403:
console.error('접근이 거부되었습니다:', error.message);
break;
case 429:
console.error('요청 제한을 초과했습니다. 잠시 후 재시도하세요.');
break;
default:
console.error('API 에러:', error.message);
}
}API Key 보안
Key 형식
API Key는 SB{10자}.[{32자}] 형식입니다.
text
SBK9X2M4P7Q1.abc123def456ghi789jkl012mno345pq보안 특성
- Secret은 발급 시 1회만 표시: 생성 즉시 안전한 곳에 저장하세요.
- 발급 개수 제한 없음: 필요한 만큼 API Key를 발급할 수 있습니다.
- SHA-256 해싱: 서버에 원본 Secret을 저장하지 않으며, SHA-256 해시값만 저장합니다.
- IP 화이트리스트:
allow_ips필드를 설정하여 특정 IP에서만 API Key를 사용하도록 제한할 수 있습니다. - Best Practice: 주기적으로 키를 교체하고, 환경(개발/스테이징/프로덕션)별로 서로 다른 키를 사용하세요.
환경 분리
Production과 Sandbox 환경은 완전히 분리되어 있으며, 각각 별도의 인증 정보와 충전금 잔액을 사용합니다.
| 항목 | Production | Sandbox |
|---|---|---|
| 도메인 | api.sweetbook.com | api-sandbox.sweetbook.com |
| 용도 | 실제 서비스 (Live) | 개발 및 테스트 |
| 인증 정보 | 별도 API Key | 별도 API Key |
| 충전금 잔액 | 별도 관리 | 별도 관리 |
환경에 대한 자세한 내용은 환경 이해하기를 참고하세요.
보안 권장사항
API Key 관리
- 환경 변수 사용: API Key를 코드에 직접 포함하지 마세요. 환경 변수로 관리하세요.
- 클라이언트 측 노출 금지: 브라우저의 JavaScript에서 API Key를 직접 사용하지 마세요. 서버 사이드에서 API를 호출하세요.
- Git에 커밋 금지:
.env파일을.gitignore에 추가하세요. - 정기적 교체: 주기적으로 API Key를 폐기하고 새로 발급하세요.
환경 변수 예시
bash
# .env
SWEETBOOK_API_KEY=SBxxxxxxxx.xxxxxxxxxxxxxxxxjavascript
// Node.js에서 사용
const API_KEY = process.env.SWEETBOOK_API_KEY;
const response = await fetch('https://api.sweetbook.com/v1/books', {
headers: {
'Authorization': `Bearer ${API_KEY}`
}
});IP 화이트리스트
프로덕션 환경에서는 파트너 포털의 API Key 설정에서 허용 IP를 지정하여 보안을 강화하세요. 지정하지 않으면 모든 IP에서 API Key를 사용할 수 있습니다.
FAQ
Q: Sandbox 키와 Live 키의 차이는 무엇인가요?
Sandbox 키로 생성한 책과 주문은 실제 인쇄되지 않으며 과금되지 않습니다. 개발 단계에서는 Sandbox 키를 사용하고, 실제 서비스에서는 Live 키를 사용하세요.
Q: API Key가 노출되면 어떻게 하나요?
즉시 파트너 포털에서 해당 API Key를 폐기하고 새로운 키를 발급받으세요. 폐기된 키로는 더 이상 API를 호출할 수 없습니다.
Q: API Key는 몇 개까지 발급할 수 있나요?
계정당 여러 개의 API Key를 발급할 수 있습니다. 서비스나 환경별로 별도의 키를 사용하는 것을 권장합니다.
Q: Postman에서 테스트하려면 어떻게 하나요?
Postman의 Authorization 탭에서 Type을 Bearer Token으로 선택하고, Token에 API Key를 입력하세요.
Rate Limiting에 대한 자세한 내용은 Rate Limiting 가이드를 참고하세요.