API Keys Reference

This page provides detailed information about VesuvioPay API key types, formats, management, and best practices.

Overview

VesuvioPay uses API key pairs for authentication, similar to Stripe's model. Each API key pair consists of:

• Publishable Key (Public) - Safe for client-side use
• Secret Key (Private) - Server-side only, keep secure

For detailed authentication workflows, see the Authentication Guide.

Key Types

Publishable Key (Public API Key)

Format: pk_{environment}_{random_string}

Examples:

• Test: pk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
• Live: pk_live_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4

Characteristics:

• ✅ Safe to expose in frontend code
• ✅ Can be embedded in mobile apps
• ✅ Can be committed to version control (test keys)
• ⚠️ Limited permissions (read-only and cart operations with JWT)

Use Cases:

• Store configuration retrieval
• Company branding information
• Cart operations (with customer JWT authentication)
• Product availability checking

API Endpoints Available:

• GET /api/v1/sdk/store/{storeId}/checkout-settings
• GET /api/v1/sdk/store/{storeId}/branding
• GET /api/v1/sdk/cart/{storeId} (requires JWT)
• POST /api/v1/sdk/cart/store/{storeId}/item (requires JWT)
• POST /api/v1/sdk/cart/store/{storeId}/availability

Secret Key (Private API Key)

Format: sk_{environment}_{random_string}

Examples:

• Test: sk_test_q1w2e3r4t5y6u7i8o9p0a1s2d3f4g5h6
• Live: sk_live_m9n8b7v6c5x4z3a2s1d0f9g8h7j6k5l4

Characteristics:

• ❌ NEVER expose in client-side code
• ❌ NEVER commit production keys to version control
• ✅ Full API access
• ✅ Server-side use only

Use Cases:

• Product synchronization
• Customer data retrieval and management
• Order creation and management
• Webhook endpoint configuration
• All admin operations

API Endpoints Available:

• All SDK endpoints (customers, products, orders, webhooks)
• Full CRUD operations
• Sensitive data access

Security Critical

Secret keys have full access to your store data. Treat them like passwords:

• Store in environment variables or secret managers
• Never commit to Git repositories
• Rotate regularly (every 90 days recommended)
• Revoke immediately if compromised

Key Environments

Test Environment

Purpose: Development, testing, and staging

Key Prefixes: pk_test_* and sk_test_*

Characteristics:

• Isolated test data
• No real charges processed
• Can be reset/regenerated freely
• Safe to use in CI/CD pipelines
• Webhooks point to test URLs

When to Use:

• Local development
• Automated testing
• Staging environments
• Integration testing
• Demo environments

Production Environment

Purpose: Live production applications

Key Prefixes: pk_live_* and sk_live_*

Characteristics:

• Real customer data
• Real payment processing
• Strict security requirements
• Audit logging enabled
• Webhooks point to production URLs

When to Use:

• Production applications only
• After thorough testing in test environment
• With proper secret management in place

Environment Separation

Never use production keys in development or test environments. Always maintain strict separation to prevent accidental data corruption or charges.

Key Format & Structure

Key Anatomy

pk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
│  │    └─────────────┬────────────────┘
│  │                  │
│  │                  └─ Random identifier (32 characters)
│  └─ Environment (test/live)
└─ Key type (pk/sk)

Key Properties

Component	Publishable	Secret
Prefix	pk_	sk_
Environment	test or live	test or live
Length	~40 characters	~40 characters
Character set	Alphanumeric	Alphanumeric
Expires	No (revoke manually)	No (revoke manually)

API Key States

Active

• ✅ Key is valid and can be used
• ✅ Requests are authenticated
• ✅ Full permissions granted

Revoked

• ❌ Key is permanently disabled
• ❌ Cannot be reactivated
• ❌ All requests return 401 UNAUTHORIZED
• ⚠️ Must generate new key pair

Revocation is Permanent

Once a key is revoked, it cannot be reactivated. You must generate a new key pair.

Key Management

Creating API Keys

1. Log in to VesuvioPay Dashboard
2. Navigate to Settings > API Keys
3. Click Generate New Key Pair
4. Select environment (Test or Live)
5. Copy both keys immediately
6. Store securely

First Time Setup

When generating keys for the first time:

1. Start with test keys
2. Test integration thoroughly
3. Generate live keys only when ready for production
4. Keep test and live keys in separate systems

Viewing API Keys

• Publishable keys: Fully visible in dashboard
• Secret keys: Only shown once during creation
  • After creation, only last 4 characters shown
  • Cannot retrieve full key - must regenerate if lost

Rotating API Keys

Recommended Rotation Schedule:

• Test keys: As needed
• Production keys: Every 90 days

Zero-Downtime Rotation Process:

1. Generate new key pair
2. Deploy new keys to 50% of infrastructure
3. Monitor for errors (24 hours recommended)
4. Deploy to remaining infrastructure
5. Wait 24-48 hours
6. Revoke old keys

// Example: Gradual key rotation
const apiKey = process.env.ROLLOUT_PERCENTAGE > 50
  ? process.env.NEW_VESUVIO_SECRET_KEY
  : process.env.OLD_VESUVIO_SECRET_KEY;

Revoking API Keys

When to Revoke:

• Key is compromised or leaked
• Employee with access leaves company
• Regular rotation schedule
• Decommissioning application
• Security incident

How to Revoke:

1. Dashboard: Settings > API Keys
2. Find the key (identified by last 4 characters and creation date)
3. Click Revoke
4. Confirm revocation
5. Generate new keys if needed

Impact:

• Immediate: All requests with revoked key fail
• Cannot be undone
• Must generate replacement key pair

Key Scopes & Permissions

Store-Level Scoping

Each API key is scoped to a single store:

• ✅ Access to resources in that store only
• ❌ Cannot access other stores
• ❌ Cannot perform cross-store operations

Example Error (wrong store):

{
  "success": false,
  "message": "API key does not have access to this store",
  "errorCode": "NO_STORE_ACCESS"
}

Permission Matrix

Operation	Publishable	Secret
Get store settings	✅	✅
Get branding	✅	✅
Cart operations (with JWT)	✅	✅
Product availability	✅	✅
Get customers	❌	✅
Sync products	❌	✅
Create orders	❌	✅
Manage webhooks	❌	✅

Security Best Practices

1. Storage

✅ DO:

• Store in environment variables
• Use secrets management (AWS Secrets Manager, Azure Key Vault)
• Encrypt at rest
• Use separate keys per environment

❌ DON'T:

• Hardcode in source code
• Commit to version control (production keys)
• Store in client-side code (secret keys)
• Share via email or chat

// ✅ Good - Environment variables
const secretKey = process.env.VESUVIO_SECRET_KEY;

// ❌ Bad - Hardcoded
const secretKey = 'sk_live_abc123...'; // NEVER DO THIS

2. Access Control

Limit who can view/manage API keys:

• Use role-based access control (RBAC)
• Audit key access regularly
• Require 2FA for key management
• Log all key operations

3. Network Security

Restrict API key usage:

• Use HTTPS only (TLS 1.2+)
• Implement IP whitelisting (when available)
• Use VPN for sensitive operations
• Monitor for unusual traffic patterns

4. Monitoring & Alerts

Set up alerts for:

• Failed authentication attempts
• Unusual request volumes
• Requests from unexpected IPs
• Key rotation reminders
• Permission errors

// Example monitoring
if (response.errorCode === 'INVALID_API_KEY') {
  logger.error('Invalid API key used', {
    endpoint: req.url,
    ip: req.ip,
    timestamp: new Date()
  });
  alertSecurityTeam('Potential API key issue detected');
}

5. Incident Response

If a key is compromised:

1. Immediate (within minutes):

   • Revoke compromised key in dashboard
   • Generate new key pair
   • Notify security team

2. Short-term (within hours):

   • Deploy new keys to production
   • Review access logs for suspicious activity
   • Audit affected resources

3. Long-term (within days):

   • Investigate how key was compromised
   • Implement additional controls
   • Update security procedures
   • Train team on best practices

API Key Headers

Request Headers

Include your API key in the X-API-Key header:

curl https://api.vesuviopay.com/api/v1/customers \
  -H "X-API-Key: sk_test_your_secret_key"

// JavaScript
fetch('https://api.vesuviopay.com/api/v1/customers', {
  headers: {
    'X-API-Key': 'sk_test_your_secret_key',
    'Content-Type': 'application/json'
  }
});

// C#
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "sk_test_your_secret_key");
var response = await client.GetAsync("https://api.vesuviopay.com/api/v1/customers");

Combined with JWT (Cart Operations)

curl https://api.vesuviopay.com/api/v1/sdk/cart/{storeId} \
  -H "X-API-Key: pk_test_your_publishable_key" \
  -H "Authorization: Bearer customer_jwt_token"

Rate Limiting

API keys are subject to rate limiting. See Rate Limiting for details.

Rate Limit Headers:

• X-RateLimit-Limit: Total requests allowed per window
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: When the limit resets (Unix timestamp)

Troubleshooting

Common Errors

Error	Cause	Solution
INVALID_API_KEY	Key is malformed or not found	Verify key format and value
API_KEY_INACTIVE	Key has been revoked	Generate new key pair
NO_STORE_ACCESS	Wrong store for this key	Use correct key for the store
ACCESS_DENIED	Insufficient permissions	Use secret key for this operation

Debugging Checklist

• Verify API key format (pk_/sk_ prefix)
• Check environment (test vs live)
• Confirm key is active (not revoked)
• Verify X-API-Key header is set
• Check store ID matches key's store
• Ensure HTTPS is used
• Verify no extra spaces or line breaks in key

FAQ

Can I regenerate the same API key if lost?

No, if you lose a secret key, you must generate a new key pair. The full secret key is only shown once during creation.

How many API keys can I create?

There's no hard limit, but we recommend:

• 1 key pair per environment (test, staging, production)
• 1 key pair per application/service
• Avoid creating unnecessary keys

Can I use the same key across multiple stores?

No, each API key is scoped to a single store. For multiple stores, you need separate key pairs for each.

Do API keys expire?

No, API keys do not expire automatically. However, we recommend rotating them every 90 days for security.

What happens if I commit a production key to Git?

1. Revoke the key immediately
2. Generate a new key pair
3. Update your application
4. Audit logs for unauthorized access
5. Use .gitignore to prevent future commits
6. Consider using Git secrets scanning tools

Can I limit API key permissions?

Currently, permissions are determined by key type (publishable vs secret). Granular permissions are on our roadmap.

Related Documentation

• Authentication Guide - Using API keys for authentication
• Error Handling - Handling authentication errors

Need Help?

• Support: support@vesuviopay.com
• Security Issues: security@vesuviopay.com
• Documentation: https://docs.vesuviopay.com