Authentication

Volr Checkout API는 API Key 인증을 사용합니다.

Getting Your API Key

1. Volr Dashboard에 로그인
2. 프로젝트 선택
3. Settings → API Keys 탭
4. API Key 복사

API Key는 volr_sk_ 접두사로 시작합니다.

Using the API Key

모든 API 요청의 x-api-key 헤더에 API Key를 포함하세요.

curl -X GET https://api.volr.io/dashboard/projects/{projectId}/checkouts \
  -H "x-api-key: volr_sk_your_api_key_here"

Security Best Practices

1. Server-Side Only

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

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

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

2. Environment Variables

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

# .env
VOLR_API_KEY=volr_sk_xxx
VOLR_PROJECT_ID=your_project_id

// app.js
const apiKey = process.env.VOLR_API_KEY;

3. Key Rotation

보안 사고가 발생하면 즉시 API Key를 재발급하세요.

Dashboard → Settings → API Keys → Regenerate

Error Responses

Missing API Key

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

Invalid API Key

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Project Mismatch

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not belong to this project"
  }
}

Rate Limiting

API 요청에는 Rate Limit이 적용됩니다:

• 100 requests/minute per project

Rate Limit 초과 시 429 Too Many Requests 응답을 받습니다.

{
  "ok": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

CORS

Volr API는 서버 간 통신용으로 설계되었습니다. 브라우저에서 직접 호출하면 CORS 에러가 발생할 수 있습니다.

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

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