Guides / Authentication

인증과 API 키

모든 요청은 API 키로 인증합니다. 계정은 신청을 받아 발급하고, 키는 계정에 로그인해 개발자 콘솔에서 직접 만듭니다. 플랜과 한도는 키가 아니라 계정에 붙습니다.

키 종류

API 키 종류
키	쓰는 곳	발급 조건	계정당 활성 키
`ck_live_…`	Data API `https://api.chickstockfi.com/openapi/v1`	Data API 플랜(PoC · Launch · Business · Scale · Enterprise)이 있는 계정	유료 등급 3개 · PoC 2개
`ck_pers_…`	PRO API `https://api.chickstockfi.com/openapi/pro/v1`와 MCP 서버	PRO 플랜(Data · Ask · Bundle)이 있는 계정	2개
`ck_mcp_at_…`	MCP 서버	AI 도구가 OAuth로 연결할 때 자동 발급(접근 토큰 1시간, 갱신 토큰 30일). 직접 만들지 않습니다.	연결 20개

요청 헤더

키는 두 헤더 중 하나로 보냅니다. 둘 다 보내면 X-API-Key를 씁니다. 쿼리 문자열로는 받지 않습니다.

삼성전자 · 005930

http

GET /openapi/v1/news?symbol=005930 HTTP/1.1
Host: api.chickstockfi.com
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxx

# 또는
X-API-Key: ck_live_xxxxxxxxxxxxxxxx

키 범위

두 API의 키는 서로 열리지 않습니다.

Data API 키(ck_live_)로 PRO API를 부르면 401 WRONG_KEY_SCOPE를 받습니다. MCP 서버는 예외로, Data API 키로 연결하면 Data API 도구가 열립니다(MCP 연결).
PRO API 키(ck_pers_)로 Data API를 부르면 401 UNAUTHORIZED를 받습니다.
없는 키나 폐기된 키는 두 API 모두 401 INVALID_KEY입니다.

계정과 플랜

계정은 이용 신청을 검토한 뒤 발급합니다. 셀프 가입은 없고, 받은 계정 ID와 비밀번호로 개발자 콘솔에 로그인합니다.
PoC는 기본 7일 체험입니다(기간은 협의로 조정할 수 있습니다). 목표 등급(Launch · Business · Scale)의 체험 한도로 모든 엔드포인트를 쓰고, 목표 등급을 정하지 않으면 Launch입니다. 기간이 끝나면 계정의 모든 키가 403 POC_ENDED로 멈추고, 기간 연장이나 정식 계약 후 같은 키로 다시 열립니다.
유료 등급(Launch · Business · Scale · Enterprise)과 PRO 플랜은 계약을 확인한 뒤 계정에 적용합니다. 적용되면 이미 만든 키에도 바로 반영됩니다.
하루 호출 한도는 계정 단위라 같은 계정의 키가 함께 씁니다. Data API의 분당 한도는 키마다 따로 셉니다. 자세한 내용은 호출 한도와 쿼터를 보세요.

키 보관

키 전체 값은 발급할 때 한 번만 보여 줍니다. 서버에는 SHA-256 해시만 남아서 분실하면 다시 보여 줄 수 없고, 새로 발급해야 합니다.
키는 서버에서만 쓰세요. 브라우저 코드, 모바일 앱 번들, 공개 저장소에 넣지 마세요. ck_live_ · ck_pers_ 접두사로 유출 검사 규칙을 만들어 두면 좋습니다.
로그나 문의 메일에는 키 전체 대신 콘솔에 보이는 앞부분(예: ck_live_8fA2c1…)만 남기세요.

교체와 폐기

콘솔의 교체는 같은 이름·범위로 새 키를 만들고 이전 키를 그 자리에서 폐기합니다. 이전 키로 보내는 요청은 바로 401 INVALID_KEY를 받습니다.

서비스를 멈추지 않고 바꾸려면 활성 키 상한 안에서 아래 순서로 진행하세요.

콘솔에서 새 키를 만듭니다(활성 키는 유료 등급 3개, PoC 2개, PRO API 2개까지).
새 키로 배포하고 요청이 정상인지 확인합니다.
이전 키를 폐기합니다. 폐기한 키는 되살릴 수 없습니다.

키가 유출된 것 같다면

콘솔에서 해당 키를 바로 교체하거나 폐기하세요. 이상 호출이 의심되면 시각과 키 앞부분을 help@alpsoft.io로 알려 주세요.

MCP 연결의 OAuth

Claude·ChatGPT 같은 AI 도구는 키 대신 OAuth 2.1로 MCP 서버에 연결할 수 있습니다. 범위(scope)는 mcp 하나이고, 쓸 수 있는 도구는 계정의 PRO 플랜이 정합니다. 절차는 MCP 연결에 정리했습니다.