본문으로 건너뛰기

Authentication

Volr는 용도에 따라 두 종류의 API 키를 제공합니다.

API Key 종류​

키 종류접두사용도노출 여부
API Keyvolr_sk_프론트엔드/SDK - 사용자 인증, 결제 실행클라이언트 코드에 노출 가능
Server Keyvolr_server_백엔드 전용 - Checkout 생성, 환불절대 노출 금지

Checkout API 연동 시​

Server Key만 사용합니다. API Key는 SDK/프론트엔드용이며, Checkout API 연동에는 필요하지 않습니다.

Server Key 발급받기​

  1. Volr Dashboard에 로그인
  2. 프로젝트 선택
  3. Settings → Security로 이동
  4. Server Key 복사

Server Key 사용하기​

Checkout API 요청 시 x-api-key 헤더에 Server Key를 포함하세요.

curl -X POST https://api.volr.io/v1/checkouts \
  -H "x-api-key: volr_server_your_server_key_here" \
  -H "Content-Type: application/json" \
  -d '{...}'
Server Key 보안

Server Key는 절대 클라이언트 코드에 노출하면 안 됩니다. 백엔드 서버에서만 사용하세요.

Security Best Practices​

1. Server Key: 서버 사이드 전용​

Server Key는 반드시 서버 사이드에서만 사용하세요.

// ✅ Good: Server-side (Node.js)
const serverKey = process.env.VOLR_SERVER_KEY;

// ❌ Bad: Client-side (브라우저, React, etc.)
const serverKey = "volr_server_xxx"; // 절대 금지!

2. Environment Variables​

키를 코드에 직접 작성하지 마세요.

# .env
VOLR_SERVER_KEY=volr_server_xxx
// backend/app.js
const serverKey = process.env.VOLR_SERVER_KEY;

3. Key Rotation​

Server Key 보안 사고가 의심되면 지원팀에 문의하세요.

Error Responses​

Missing Server Key​

{
  "ok": false,
  "error": {
    "code": "SERVER_KEY_REQUIRED",
    "message": "Server API key is required"
  }
}

Invalid Key Type​

{
  "ok": false,
  "error": {
    "code": "INVALID_KEY_TYPE",
    "message": "This endpoint requires a server key (volr_server_...)"
  }
}

Project Not Found​

{
  "ok": false,
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project not found"
  }
}

CORS​

Volr Checkout API (/v1/checkouts)는 서버 간 통신용으로 설계되었습니다. 브라우저에서 직접 호출하면 실패합니다.

키오스크나 외부 디바이스에서는 반드시 서버를 통해 API를 호출하세요.

[Kiosk] → [Your Server] → [Volr API]