파트너 API

파트너용 서버 간 API: 키 발급, 스토어프론트 설정과 위치 조회, 고객 생성, 요금제 지급, 구독 링크 관리를 자체 사이트나 Telegram 봇에서 할 수 있습니다.

파트너 API를 사용하면 CreateYourVPN 위에 자체 사이트, 자체 대시보드 또는 Telegram 봇을 만들 수 있습니다.

API가 다루는 범위는 고객, 구독, 요금제, 스토어프론트 설정입니다. 서버, 노드, 패널, SSH 자격 증명 같은 인프라는 공개 계약에 포함되지 않습니다.

서버 간 통신 전용입니다. API 키는 서버에 저장하고 프런트엔드 코드에 넣지 마세요. 브라우저 헤더가 붙은 요청은 403 browser_forbidden으로 거부됩니다.

키 발급받기

대시보드에서 계정 메뉴 → "API"를 열고 "키" 탭을 선택합니다.

키에 이름을 붙이고(Telegram 봇, 랜딩 페이지) 필요한 권한만 고릅니다.

"키 발급"을 누르고 값 전체를 복사합니다. 해시만 저장되므로 secret은 한 번만 표시됩니다.

파트너마다 활성 키는 최대 5개까지 둘 수 있습니다. 키를 교체하려면 새 키를 발급하고 연동을 업데이트한 다음 이전 키를 폐기하세요.

키는 bearer 토큰으로 보냅니다.

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

프록시가 Authorization을 사용하는 클라이언트에서는 X-API-Key: cyv_live_…도 쓸 수 있습니다.

키 형식은 cyv_live_<key_id>_<secret>입니다. 앞부분(key_id)은 공개 정보입니다: 대시보드에 표시되며 지원팀에 알려 줘도 안전합니다. 뒷부분은 secret입니다.

스토어프론트 데이터만 읽는 연동이라면 config:read로 충분합니다. users:read나 users:write는 연동에 해당 고객 작업이 필요할 때만 추가하세요.

실행 가능한 전체 계약은 공개 Postman 컬렉션에 있습니다. 모든 엔드포인트, 권한, 매개변수, 요청 본문, 응답 예시, 안정적인 오류 코드가 들어 있습니다. 컬렉션은 백엔드 계약에서 생성되며, 요청과 응답 스키마의 최신 기준입니다.

모든 엔드포인트를 살펴보고 컬렉션을 자신의 workspace로 fork하세요.

한도는 요청의 IP 주소와 관계없이 키마다 따로 계산됩니다.

GET /users에 별도 한도가 있는 이유는 요청할 때마다 전체 고객 목록을 불러오기 때문입니다. 일상적인 조회에는 GET /users/{id} 또는 externalId 검색을 사용하세요.

권장 접근 방식. 생성 시 반환되는 CreateYourVPN 고객 ID를 저장하고, 이후 조회에는 GET /users/{id}를 사용하세요. externalId로 자체 식별자와 연결할 수 있습니다.

Idempotency-Key 헤더가 필요한 작업은 세 가지입니다: 요금제 지급, 구독 링크 재설정, 고객 삭제.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

같은 키로 24시간 안에 요청을 반복하면 작업을 다시 실행하는 대신 저장된 응답이 반환됩니다. 덕분에 연동이 타임아웃 후 재시도해도 변경이 중복되지 않습니다.

비즈니스 이벤트(예: 결제 한 건이나 작업 하나)마다 키를 하나 만들고, 그 이벤트의 모든 재시도에 같은 키를 사용하세요.

첫 번째 시도가 아직 실행 중이거나 결과를 일시적으로 알 수 없으면, API는 작업을 다시 실행하지 않고 409 conflict를 반환합니다. 재시도할지 결정하기 전에 고객의 현재 상태를 확인하세요.

요청과 응답 스키마는 위의 공개 Postman 컬렉션을 기준으로 삼으세요.