🔐 Authentication

All API requests require authentication using an API key. This guide covers key types, rate limits, and security best practices.

API Keys

Getting Your Keys

  1. Sign in to the Developer Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Copy the key immediately - it won't be shown again

Key Formats

Prefix Environment Billing
vk_test_ Sandbox Free (mock data)
vk_prod_ Production Charges wallet
⚠️ Test Mode

Test keys return mock data and don't interact with real electricity providers. Always test thoroughly before switching to production.

Making Requests

Include your API key in the Authorization header:

HTTP Header
Authorization: Bearer vk_test_xxxxxxxxxxxxx
cURL Example
curl -X POST https://api.developers.venshack.io/v1/vending/validate \
  -H "Authorization: Bearer vk_test_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"meterNumber": "1234567890123"}'
JavaScript / Node.js
const response = await fetch('https://api.developers.venshack.io/v1/vending/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vk_test_xxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    meterNumber: '1234567890123'
  })
});

Rate Limits

API requests are rate-limited per API key:

Plan Requests per minute
Free / Test 60
Pro 600
Enterprise Custom

Rate Limit Headers

Every response includes these headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1711180200
Header Description
X-RateLimit-Limit Maximum requests per minute
X-RateLimit-Remaining Requests remaining
X-RateLimit-Reset Unix timestamp when limit resets

Security Best Practices

✅ Do

Store API keys in environment variables or secret managers. Use different keys for development and production. Rotate keys every 90 days.

❌ Don't

Never expose keys in client-side code. Never commit keys to version control. Never share keys via email or chat.

.env file
# Development
VENSHACK_API_KEY=vk_test_xxxxxxxxxxxxx

# Production (use proper secret management)
VENSHACK_API_KEY=vk_prod_xxxxxxxxxxxxx

Troubleshooting

"Invalid API key"

"API key required"

"Rate limit exceeded"