Authentication

두 가지 인증 경로

Veacon API 는 두 가지 인증 방식 중 하나를 선택할 수 있습니다.

모든 API 엔드포인트는 두 방식 중 하나만 있으면 작동합니다. 둘 다 존재 시 API Key 가 우선 적용됩니다.

1. X-API-Key (권장 — B2B)

발급

• /dashboard → API Keys 섹션에서 발급
• Starter 플랜은 로그인 시 자동 발급
• Pro 이상 플랜은 다수 키 관리 가능 (라벨, 회전, 폐기 — P5 에서 구현 예정)

형식

veacon_pk_live_<32자 hex>
veacon_pk_test_<32자 hex>  ← 테스트 모드 (P5 이후)

• prefix veacon_pk_ 는 키 타입 식별용
• DB 에는 SHA-256 해시만 저장 — 발급 직후 1회만 평문 노출

사용

curl -H "X-API-Key: veacon_pk_live_..." \
  "https://veacon.io/api/v1/markets/pulse?region=강남권&category=office&period=2026-01"

Python:

import requests
r = requests.get(
    "https://veacon.io/api/v1/markets/pulse",
    headers={"X-API-Key": "veacon_pk_live_..."},
    params={"region": "강남권", "category": "office", "period": "2026-01"},
)
print(r.json())

보안 수칙

1. 절대 프론트엔드 코드에 넣지 않습니다 (브라우저 코드에 넣으면 DevTools 로 노출)
2. 서버 환경변수(VEACON_API_KEY), 비밀 저장소(AWS Secrets, Vercel env) 에만 보관
3. 유출 의심 시 즉시 대시보드에서 회전(rotate) — 기존 키 무효화
4. 각 용도(프로덕션 / 스테이징 / CI)마다 별도 키 발급 권장 (Pro 플랜 이상)

2. veacon_session 쿠키 (브라우저)

발급 흐름

/login → Syncle Supabase 로 로그인 (이메일/비밀번호 or Google OAuth)
      → JWT access token 수령
      → Veacon /api/auth/session POST { jwt }
      → Veacon 이 JWT 검증 후 HttpOnly 쿠키 "veacon_session" 발급
      → 이후 동일 origin fetch 는 쿠키 자동 첨부

특징

• HttpOnly — JavaScript 에서 접근 불가 (XSS 방어)
• Secure — HTTPS 에서만 전송
• SameSite=Lax — CSRF 기본 방어
• 유효기간 15분 (슬라이딩 갱신 — 활동 있으면 연장)
• 프로덕션은 Domain=.veacon.io 로 하위도메인 공유

사용 (브라우저)

별도 헤더 추가 불필요 — 같은 오리진에서 fetch 하면 자동:

const r = await fetch('/api/v1/markets/pulse?region=강남권&category=office&period=2026-01', {
  credentials: 'include',
});

쿼터

쿠키 기반 무료 티어는 분당 10 호출, 월 호출 한도는 별도 제한 없음(대시보드 탐색 용). 실제 B2B 워크로드는 X-API-Key 를 사용하세요.

인증 실패 응답

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API Key"
  },
  "_meta": { "service": "veacon", "api_version": "v1" }
}

• 401 — 키/쿠키 없음 or 형식 오류
• 401 — 키/쿠키 형식은 맞지만 DB 에서 조회 실패 (해시 미스매치)
• 401 — Syncle JWT 가 만료 또는 회수됨

모든 케이스는 Errors 에 상세.

다음으로

• Rate limits & quota
• Errors
• API Reference: markets/pulse