Authentication

Volr provides two types of API keys for different use cases.

API Key Types

Key Type	Prefix	Usage	Exposure
API Key	volr_sk_	Frontend/SDK - user authentication, payment execution	Safe to expose in client code
Server Key	volr_server_	Backend only - checkout creation, refunds	NEVER expose

For Checkout API

Use Server Key only. The API Key is for SDK/frontend use and is not needed for Checkout API integration.

Getting Your Server Key

1. Log in to Volr Dashboard
2. Select your project
3. Go to Settings → Security
4. Copy your Server Key

Using the Server Key

Include the Server Key in the x-api-key header for checkout API requests.

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 Security

NEVER expose your Server Key in client-side code. It should only be used in your backend server.

Security Best Practices

1. Server Key: Server-Side Only

Server Key must be used only on server-side.

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

// ❌ Bad: Client-side (browser, React, etc.)
const serverKey = "volr_server_xxx"; // NEVER do this!

2. Environment Variables

Never hardcode keys in your source code.

# .env
VOLR_SERVER_KEY=volr_server_xxx

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

3. Key Rotation

Contact support if you suspect a security incident with your 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"
  }
}

Origin Not Allowed

When calling from a browser with an origin not in your project's whitelist:

{
  "ok": false,
  "error": {
    "code": "ORIGIN_NOT_ALLOWED",
    "message": "Origin is not allowed for this project"
  }
}

All Error Codes

Code	HTTP Status	Description
SERVER_KEY_REQUIRED	400	Missing x-api-key header
INVALID_KEY_TYPE	403	Used API Key instead of Server Key
PROJECT_NOT_FOUND	404	Invalid API key or project deleted
AUTH_PROJECT_REQUIRED	400	Missing API Key for SDK endpoints
AUTH_PROJECT_NOT_FOUND	404	Invalid API Key
ORIGIN_NOT_ALLOWED	403	Browser origin not whitelisted

CORS

Volr Checkout API (/v1/checkouts) is designed for server-to-server communication. Direct calls from browsers will fail.

For kiosks or external devices, always call the API through your server.

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