핵심 개념 · Authentication

인증 (Authentication)

이벗 API 는 요청 종류에 따라 두 가지 인증 방식을 제공합니다. 외부 셀러 시스템·자동화 스크립트는 API Key 를 사용합니다. JWT 는 이벗 내부 웹·앱 연동용입니다. 단, 페이똑딱(/v3/pay/)은 JWT 전용이며 API Key 를 지원하지 않습니다.

API Key 인증

키 한 개로 다수의 요청을 인증하는 가장 단순한 방식입니다. 서버 환경(예: 자사 ERP, 백오피스 배치)에서 사용합니다.

헤더 형식

X-API-Key: ebut_manager_live_xxxxxxxxxxxxxxxx

키 종류

형식	용도	설명
`ebut_{서비스}_test_{난수}`	개발 · 연동 확인	서비스를 연결하면 무료로 발급됩니다. 90일 유효. 조회되는 데이터는 운영 데이터와 동일하므로 운영 키와 같은 수준으로 보관해 주세요.
`ebut_{서비스}_live_{난수}`	운영	유료 구독이 있어야 발급됩니다. 구독 기간 동안 유효.

{서비스} 자리에는 인증키가 발급된 서비스 코드가 들어갑니다 — wms · manager · cam. 예를 들어 이벗WMS 의 테스트 키는 ebut_wms_test_... 형태입니다.

⚠️ 페이똑딱은 API Key 를 지원하지 않습니다 페이똑딱(/v3/pay/)은 JWT 전용입니다. X-API-Key 헤더만으로 호출하면 키 검증 없이 403 AUTH_FORBIDDEN 이 반환됩니다. 페이똑딱 연동은 help@ebut.co.kr 로 문의해 주세요.

발급 절차

인증키는 직접 발급하실 수 있습니다. 별도 신청 절차가 없습니다.

이벗 통합계정에 가입합니다.
사용 중인 이벗 서비스 계정을 연결합니다.
인증키 화면에서 test 인증키를 발급받습니다. 운영용이 필요하시면 유료 구독 후 live 인증키를 발급받습니다.
Quickstart 의 첫 호출 예제로 동작을 확인합니다.

도입 상담이나 대량 연동 문의는 help@ebut.co.kr 로 연락해 주세요.

서비스별 지원 인증

같은 서비스 안에서도 endpoint 성격에 따라 인증 수단이 제한되는 경우가 있습니다. 호출 전에 아래 표를 확인해 주세요.

서비스	API Key	JWT	제한 사항
이벗WMS	✅	✅	AI 분석 endpoint(`orders/risk` · `orders/briefing` · `inventory/risk` · `inventory/forecast` · `briefing/daily` · `shipping/bottleneck` · `claims/analysis`)는 JWT 전용, 웹훅 수신(`webhooks`)은 API Key 전용입니다.
이벗매니저	✅	✅	AI 분석 endpoint 7종은 JWT 전용입니다.
이벗캠	✅	✅	제한 없음 — 모든 endpoint 에서 둘 다 사용 가능합니다.
페이똑딱	❌	✅	JWT 전용. API Key 호출은 403 `AUTH_FORBIDDEN`.

Authorization 헤더와 X-API-Key 헤더를 함께 보내면 JWT 가 우선 적용됩니다.

JWT 인증

사용자(셀러) 단위 토큰을 발급하여 인증하는 방식입니다. 로그인 세션을 유지하는 이벗 내부 웹·앱 연동에 사용합니다.

헤더 형식

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

토큰 만료 / 갱신

만료 시각은 토큰의 exp 클레임을 따릅니다 — 발급하는 쪽이 정합니다.
만료 시 응답: HTTP 401 + AUTH_EXPIRED_TOKEN
JWT 발급 창구는 외부에 제공하지 않습니다. 외부 연동에는 API Key 를 사용해주세요 — 단 페이똑딱은 API Key 가 없으므로 help@ebut.co.kr 로 연동 문의를 주셔야 합니다.

어느 것을 써야 하나요?

상황	추천	이유
자사 ERP / WMS 와 자동 연동	API Key	장기 키 하나로 서버 측에서 안전하게 사용
웹 / 앱 화면에서 사용자 행동	JWT	사용자별 토큰 + 짧은 만료로 노출 위험 최소화
이벗 내부 웹·앱	JWT	사용자 세션 단위. 외부 발급 창구는 제공하지 않습니다
야간 배치 / Cron 자동화	API Key	사용자 컨텍스트 불필요

셀러 컨텍스트

요청이 어떤 셀러의 데이터를 다루는지 결정하는 방식은 서비스마다 다릅니다.

서비스	셀러 구분	설명
이벗WMS	다중 셀러	요청에 `seller_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	접근 권한 부족 — JWT 전용 endpoint 를 API Key 로 호출했거나(페이똑딱 전체 · WMS/매니저 AI 분석), 해당 데이터 접근 권한이 없는 경우. 운영팀(help@ebut.co.kr) 문의

보안 권장사항

⚠️ 절대 하지 말 것

키를 Git / 클라이언트 코드(JS, 앱 바이너리) 에 하드코딩
로그·에러 메시지에 키 전체 출력
외부 서드파티 도구에 키 평문 전달

환경변수 / 시크릿 매니저 에 보관 (예: AWS Secrets Manager, HashiCorp Vault, .env + .gitignore)
운영(..._live_...) / 테스트(..._test_...) 키를 환경별로 분리
키 유출 의심 시 즉시 help@ebut.co.kr 로 재발급 요청 — 기존 키는 즉시 비활성화됩니다
JWT 는 짧은 만료 + refresh 방식으로 운영 — 장기 보관 금지
HTTPS 통신만 사용 (게이트웨이는 HTTP 거부)