인증

EasterAd Core API는 서버 간 통신(Server-to-Server) 및 자동화 시스템 연동을 위해 HTTP 표준 Bearer 토큰 기반 인증 방식을 사용합니다. 콘솔에서 발급받은 API 키를 요청 헤더에 포함하여 호출합니다.

1. 인증 헤더 전송 규약

모든 API 요청의 HTTP Authorization 헤더에 Bearer 토큰 형태로 API 키를 전달해야 합니다.

Authorization: Bearer ea_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_****************

cURL 호출 예시

curl -X GET "https://www.easterad.com/api/core/organization/{organizationId}/balance" \
  -H "Authorization: Bearer ea_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_****************" \
  -H "Accept: application/json"

2. API 키 권한과 스코프 (Role-Based Access)

API 키는 독립적인 사용자가 아니며, 키 생성 시 지정된 ’조직 역할(Role)’의 권한을 그대로 상속받습니다.

flowchart LR
    A["API 키 (ea_...)"] --> B["할당된 역할 (예: Viewer, Finance)"]
    B --> C["리소스별 허용 액션 (조회, 생성, 수정 등)"]

최소 권한의 원칙: 자동화 봇의 목적에 부합하는 최소한의 권한(예: 단순 잔액 모니터링 봇인 경우 잔액 조회 권한만 포함된 커스텀 역할)을 부여하세요.
권한 부족 시 거부: 호출하려는 엔드포인트의 요구 권한이 역할에 포함되어 있지 않으면 403 Forbidden이 반환됩니다. 자세한 진단 방법은 오류 디버깅 가이드를 확인하세요.

3. 인증 단계 에러 코드

인증 처리 중 문제가 발생하면 아래의 전용 코드가 반환됩니다.

HTTP 상태	에러 코드 (`code`)	주요 발생 원인	해결 방안
`401`	`UNAUTHORIZED`	`Authorization` 헤더 자체가 누락되었거나 Bearer 형식이 아닙니다.	헤더에 `Authorization: Bearer ea_...`를 정확히 전달하세요.
`401`	`INVALID_API_KEY`	키 문자열 오타, 폐기/삭제된 키, 또는 비활성화된 계정의 키입니다.	대시보드에서 키 상태를 확인하고 필요 시 재발급하세요.
`401`	`API_KEY_EXPIRED`	설정된 유효 기간(만료일)이 경과한 키입니다.	새 키를 발급받거나 키 정책에서 만료일을 연장하세요.
`403`	`IP_NOT_WHITELISTED`	키 정책에 등록된 IP 허용 목록(Whitelist) 밖에서 호출되었습니다.	호출 서버의 공인 IP를 대시보드 허용 목록에 추가하세요.
`429`	`RATE_LIMIT_EXCEEDED`	키별 호출 한도를 초과했거나 인증 실패 누적으로 일시 차단되었습니다.	호출 주기를 조절하고 지수 백오프를 적용하세요.

4. 운영 환경 보안 체크리스트

프로덕션 환경에서 API 키를 안전하게 운용하기 위해 다음 사항을 점검하세요.

환경 변수 주입: API 키는 절대 소스 코드나 클라이언트 빌드 산출물, 형상관리(Git)에 포함하지 말고, 비밀 관리 시스템(Vault, AWS Secrets Manager 등)이나 런타임 환경 변수로 주입하세요.
고정 공인 IP 허용 목록 적용: 운영 서버에서 호출하는 API 키에는 반드시 호출 서버의 고정 공인 IP 주소만 등록하세요.
만료일 설정: 키 유출 피해를 방지하기 위해 최대 90~180일 주기의 만료일을 설정하고 주기적으로 로테이션하세요.
무중단 롤링 교체: 키를 교체할 때는 API 키 관리 가이드에 따라 신규 키를 먼저 발급하여 배포한 후 기존 키를 폐기하세요.

다음 단계

오류 응답 구조 및 카탈로그: 일반 비즈니스 오류 코드 및 403 트러블슈팅 절차를 확인합니다.
페이지네이션과 API 규약: 데이터 포맷과 목록 조회 패턴을 알아봅니다.