API 키

API 요청을 인증하고 키를 안전하게 보관하세요.

소개

모든 Tokenz API v2 요청은 Bearer 토큰으로 전송하는 비밀 API 키로 인증합니다.

bash

curl https://api.tokenz.one/v2/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

Tokenz API v2에서는 비밀 키만 사용하며, 공개용 또는 클라이언트용 키는 사용되지 않습니다. 비밀 키는 계정의 결제를 생성하고 주문 데이터를 읽을 수 있으므로 절대로 서버 외부로 노출하면 안 됩니다.

대시보드의 Developers → API keys에서 키를 생성하고 관리합니다.

테스트 키와 라이브 키

각 키는 하나의 모드에 속합니다.

필요하면 좌우로 스크롤하세요

접두사	모드	실제 결제
`secret_test_…`	테스트	없음 — 모의 결제만 수행
`secret_live_…`	라이브	있음 — 실제 결제

개발 및 테스트에는 테스트 키를 사용하고 실제 결제를 받으려면 라이브 키로 전환하세요. 테스트 키는 실제 결제를 처리할 수 없고 라이브 키는 테스트 모드에 사용할 수 없습니다. 환경별로 분리하여 설정하세요(예: 환경마다 다른 TOKENZ_SECRET_KEY 변수).

비밀 키 보호

클라이언트에서 안전하게 사용할 수 있는 키가 없으므로 비밀번호처럼 취급하세요.

서버에서만 사용하세요. 브라우저 코드, 모바일 앱, SPA 번들 등 사용자 기기에 배포되는 곳에 넣지 마세요.
버전 관리 저장소에 커밋하지 말고, 로그, 오류 메시지, URL에도 포함하지 마세요.
코드가 아닌 환경 변수나 비밀 정보 관리자에 저장하세요.

키는 생성할 때 한 번만 표시됩니다. 즉시 복사해 안전하게 보관하세요. 잃어버렸다면 복구를 시도하지 말고 새 키를 생성하세요.

필요한 권한 범위만 부여

키 생성 시 Checkout Session 생성·조회, 주문 조회·취소, 아이템 지급 기록, 상품 조회, 환불 생성·조회, 코드 검증·사용, 구독 요금제 변경 등의 **권한 범위(scopes)**를 선택합니다.

키마다 필요한 최소 권한만 부여하세요.

연동 또는 서비스별로 별도 키를 만들고 사용하는 권한만 부여하세요. 주문 조회만 하는 보고 작업에는 환불이나 Checkout 권한이 필요하지 않습니다.
제한된 키가 유출되면 피해 범위를 줄일 수 있고, 다른 기능에 영향을 주지 않고 해당 키만 폐기할 수 있습니다.

키 교체 및 폐기

교체: 새 키를 생성해 배포한 후 Developers → API keys에서 기존 키를 삭제하세요. 여러 키를 동시에 보유할 수 있어 중단 없이 교체할 수 있습니다.
저장소 커밋, 티켓 붙여넣기, 로그 기록 등으로 노출되었다면 즉시 삭제하세요. 삭제하면 폐기되어 해당 키를 쓰는 모든 요청이 중단됩니다. 그 후 대체 키를 발급하세요.

웹훅 서명 비밀키

웹훅 엔드포인트의 서명 비밀키는 API 키와 별개입니다. Tokenz가 이를 사용해 서명하며, 판매자는 원본 요청 본문으로 Tokenz-Signature 헤더를 검증하여 진위를 확인합니다. API 키처럼 서버에만 보관하세요.

서명 검증 방법은 웹훅을 참고하세요.