인증
Authentication — header-based partner authentication and key management. English text follows each Korean section.
헤더 인증
모든 FI 엔드포인트(공개 GET /fi/health 제외)는 요청마다 두 개의 헤더를 요구합니다.
EN — Every FI endpoint (except the public GET /fi/health) requires two headers on each request.
| 헤더 | 설명 |
|---|---|
X-Client-Id | 발급받은 파트너 클라이언트 ID / your partner client id |
X-API-Key | 발급받은 API 키(평문). 서버는 BCrypt 해시와 대조 / your API key (plaintext); verified against a BCrypt hash server-side |
curl -s https://trendy.storydot.kr/superapp/api/fi/whoami \
-H "X-Client-Id: YOUR_CLIENT_ID" \
-H "X-API-Key: YOUR_API_KEY"헤더가 없거나 키가 틀리면 SW2102(INVALID_API_KEY), 클라이언트가 정지 상태면
SW2101(PARTNER_CLIENT_SUSPENDED)이 반환됩니다.
EN — Missing/invalid credentials return SW2102 (INVALID_API_KEY); a suspended
client returns SW2101 (PARTNER_CLIENT_SUSPENDED).
환경(environment)과 키
키는 발급 시 LIVE 또는 SANDBOX 환경에 결속됩니다. 기본 URL은 동일하며, 서버가 인증된 키의 환경을 보고 분기합니다.
- SANDBOX — 실제 사용자 조회 코드 경로에 도달하지 않고, 결정적 합성 응답만 반환
- LIVE — 동의 기반 실데이터. 모든 조회가 접근로그에 기록
현재 키의 환경은 GET /fi/whoami로 확인할 수 있고, 점수 응답에도
environment 필드("LIVE" | "SANDBOX")가 포함됩니다.
EN — A key is bound to LIVE or SANDBOX at issuance. The base URL is shared; the server
branches on the authenticated key's environment. A SANDBOX key never reaches real-subject lookup code.
Check your environment via GET /fi/whoami; score responses also carry an
environment field ("LIVE" | "SANDBOX").
키 관리 수칙
- 1회 표시: 키는 발급 시 한 번만 평문으로 표시됩니다. 서버에는 해시만 저장되어 재조회가 불가능합니다. 분실 시 재발급을 요청하세요.
- 시크릿 보관: 키를 코드·저장소·로그에 넣지 말고 시크릿 매니저/환경변수로 주입하세요.
- 서버 간 통신 전용: 브라우저·모바일 앱에 키를 내장하지 마세요. FI 백엔드에서만 호출해야 합니다.
- 회전: 키가 노출됐다고 의심되면 즉시 운영팀에 회전(재발급+구키 폐기)을 요청하세요.
- 최근 사용 시각: 서버는 인증 성공 시 클라이언트의
last_used_at을 갱신하여 미사용 키를 식별합니다.
EN — Key management rules: the key is shown in plaintext only once at issuance
(hash-only storage; it cannot be retrieved later — request re-issuance if lost). Keep it in a secrets
manager, never in code, repos or logs. Server-to-server only — never embed the key in a browser or mobile
app. Request rotation immediately on suspected exposure. The server updates the client's
last_used_at on each successful authentication so unused keys can be identified.
속도 제한
기본 속도 제한은 60 req/min입니다. 초과 시 HTTP 429와
Retry-After: <seconds> 헤더가 반환됩니다. 재시도 정책은 에러 페이지를 보세요.
EN — Default rate limit is 60 req/min. Exceeding it returns HTTP 429 with a
Retry-After: <seconds> header. See Errors for the retry policy.
웹훅 서명 키
웹훅 엔드포인트를 등록하면 별도의 서명 시크릿이 생성되어 1회 평문으로 반환됩니다.
API 키와는 다른 값이며, 수신한 웹훅의 X-HACS-Signature 검증에만 사용합니다.
상세는 웹훅 페이지를 보세요.
EN — Registering a webhook endpoint generates a separate signing secret,
returned in plaintext once. It differs from the API key and is used only to verify the
X-HACS-Signature header on received webhooks. See Webhooks.