인증

퍼스톡 OpenAPI는 OAuth 2.0 Client Credentials Grant를 씁니다. API 키(client_id + client_secret)로 1시간짜리 access token을 받고, 모든 요청의 Authorization 헤더에 실어 보내요.

[API 키 발급 (웹, 1회)] → [POST /oauth2/token] → access_token (1시간)
                                                    ↓
                               Authorization: Bearer <access_token>

API 키 발급

퍼스톡에 Google 계정으로 로그인해요.
프로필 → OpenAPI 탭에서 키 이름을 적고 새 키 발급을 눌러요.
화면에 나온 client_id(fsk_로 시작)와 client_secret(fss_로 시작)을 복사해요.

규칙	내용
secret 노출	발급 직후 한 번만 보여요. 서버엔 해시만 저장돼서 다시 볼 수 없어요. 잃어버렸으면 폐기하고 새로 발급하세요.
개수	계정당 활성 키 최대 5개
범위	키는 발급한 본인 계정만 조작해요. 다른 사람 계정을 대신 조작하는 방법은 없어요.

access token 받기

POST https://api.furstock.trade/oauth2/token

OAuth 2.0 표준대로 application/x-www-form-urlencoded로 보내요. application/json도 받습니다.

필드	필수	설명
`grant_type`	✅	항상 `client_credentials`
`client_id`	✅	발급받은 client_id
`client_secret`	✅	발급받은 client_secret

curl -s https://api.furstock.trade/oauth2/token 
  -d grant_type=client_credentials 
  -d client_id=$FURSTOCK_CLIENT_ID 
  -d client_secret=$FURSTOCK_CLIENT_SECRET

응답 200

{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600 }

상태	`error`	의미
400	`invalid_request`	필드 누락·형식 오류
401	`invalid_client`	client_id/secret이 틀렸거나 폐기된 키
429	`rate_limited`	같은 client_id로 분당 30회 초과

토큰에는 refresh token이 없어요. 만료(expires_in초) 몇 분 전에 같은 요청으로 새 토큰을 받으세요. 요청마다 토큰을 새로 받지는 마세요. 분당 30회 제한에 걸립니다.

API 호출

모든 요청에 헤더를 붙여요.

GET /v1/accounts/holdings HTTP/1.1
Host: api.furstock.trade
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

시세·종목·커뮤니티 조회처럼 공개된 API는 토큰 없이도 호출돼요. 각 API 표의 인증 열을 보세요.

토큰이 유효한지는 GET /v1/me로 확인할 수 있어요.

{ "userId": "8b6b74e7-2bf7-42ad-8cfc-534ed05708b8", "isAdmin": false, "authMethod": "api_key" }

키 폐기

프로필 → OpenAPI 탭에서 폐기를 누르면:

그 키로 새 토큰을 받을 수 없어요(401 invalid_client).
이미 받은 토큰도 즉시 막혀요. 폐기 후 요청은 401이에요. 드물게 최대 30초까지 늦어질 수 있어요.
되살릴 수 없어요. 필요하면 새로 발급하세요.

API 키로 할 수 없는 것

키가 유출돼도 피해가 커지지 않도록, 다음은 퍼스톡 웹에 로그인한 상태에서만 할 수 있어요. API 키 토큰으로 호출하면 403 session_required가 와요.

작업	이유
API 키 발급·목록·폐기 (`/v1/api-keys`)	유출된 키로 새 키를 만들어 계속 쓰는 걸 막기 위해
회원 탈퇴 (`POST /v1/accounts/withdraw`)	되돌릴 수 없는 작업이라서
관리자 권한	관리자 계정의 키라도 API에선 일반 사용자로 취급돼요

보안 수칙

client_secret은 코드에 직접 쓰지 말고 환경변수나 비밀 저장소로 관리하세요. .env는 .gitignore에 넣으세요.
브라우저에서 동작하는 커스텀 클라이언트라면 secret이 사용자에게 그대로 노출돼요. 본인만 쓰는 도구에만 쓰고, 공개 웹앱에 secret을 넣지 마세요.
봇마다 키를 따로 발급하면 문제가 생긴 봇만 골라서 폐기할 수 있어요.