인증 (Authentication)
이벗 API 는 요청 종류에 따라 두 가지 인증 방식을 제공합니다. 외부 셀러 시스템·자동화 스크립트는 API Key, 웹·앱·AI 에이전트·MCP 서버는 JWT 를 사용합니다.
API Key 인증
키 한 개로 다수의 요청을 인증하는 가장 단순한 방식입니다. 서버 환경(예: 자사 ERP, 백오피스 배치)에서 사용합니다.
헤더 형식
X-API-Key: ebut_live_xxxxxxxxxxxxxxxxxxxxxx키 종류
| 접두어 | 용도 | 설명 |
|---|---|---|
ebut_test_ |
테스트 | 실거래 영향 없음. 무료 티어에서 발급. 30일 유효. |
ebut_live_ |
운영 | 실거래 호출용. 스탠다드 이상 요금제에서 발급. |
발급 절차
- help@ebut.co.kr 로 신청 (회사명·서비스·연동 목적·예상 호출량)
- 운영팀 검토 후 영업일 기준 1~2일 내 키 발급
- 키 수령 후 Quickstart 의 첫 호출 예제로 동작 확인
JWT 인증
사용자(셀러) 단위 토큰을 발급하여 인증하는 방식입니다. 로그인 세션을 유지하는 웹·앱과, 동적인 토큰 위임이 필요한 AI 에이전트(MCP) 에 적합합니다.
헤더 형식
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...토큰 만료 / 갱신
- 기본 만료: 60분 (서비스별 상이 — 매니저 60분, MCP 30분)
- 만료 시 응답: HTTP 401 +
AUTH_EXPIRED_TOKEN - 갱신: refresh token 으로 재발급 (별도 endpoint, 서비스별 안내)
어느 것을 써야 하나요?
| 상황 | 추천 | 이유 |
|---|---|---|
| 자사 ERP / WMS 와 자동 연동 | API Key | 장기 키 하나로 서버 측에서 안전하게 사용 |
| 웹 / 앱 화면에서 사용자 행동 | JWT | 사용자별 토큰 + 짧은 만료로 노출 위험 최소화 |
| AI 에이전트 / MCP 서버 | JWT | 세션 단위 위임, 게이트웨이 경유 필수 |
| 야간 배치 / Cron 자동화 | API Key | 사용자 컨텍스트 불필요 |
셀러 컨텍스트
요청이 어떤 셀러의 데이터를 다루는지 결정하는 방식은 서비스마다 다릅니다.
| 서비스 | 셀러 구분 | 설명 |
|---|---|---|
| 이벗WMS | 다중 셀러 | 요청에 seller_code 명시 (또는 토큰의 cust_code 자동 적용). 1 물류센터 = N 셀러. |
| 이벗매니저 | 단일 셀러 | 토큰에서 자동 추출. seller_code 명시 불필요. |
| 이벗캠 | 단일 시스템 | 셀러 구분 없음. 송장번호 기준 조회. |
| 페이똑딱 | 단일 시스템 | 워크스페이스(workspace_code) 기준 조회. |
401 / 403 처리
| 에러 코드 | HTTP | 의미 / 대응 |
|---|---|---|
AUTH_MISSING_TOKEN | 401 | 인증 헤더 누락 — X-API-Key 또는 Authorization 헤더 확인 |
AUTH_INVALID_TOKEN | 401 | 키/토큰 유효하지 않음 — 발급 정보 확인 또는 재발급 |
AUTH_EXPIRED_TOKEN | 401 | JWT 만료 — refresh 후 재시도 |
AUTH_FORBIDDEN | 403 | 접근 권한 부족 — 운영팀(help@ebut.co.kr) 문의 |
보안 권장사항
⚠️ 절대 하지 말 것
- 키를 Git / 클라이언트 코드(JS, 앱 바이너리) 에 하드코딩
- 로그·에러 메시지에 키 전체 출력
- 외부 서드파티 도구에 키 평문 전달
- 환경변수 / 시크릿 매니저 에 보관 (예: AWS Secrets Manager, HashiCorp Vault,
.env+.gitignore) - 운영(
ebut_live_) / 테스트(ebut_test_) 키를 환경별로 분리 - 키 유출 의심 시 즉시 help@ebut.co.kr 로 재발급 요청 — 기존 키는 즉시 비활성화됩니다
- JWT 는 짧은 만료 + refresh 방식으로 운영 — 장기 보관 금지
- HTTPS 통신만 사용 (게이트웨이는 HTTP 거부)