Skip to main content

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​

ComponentPublishableSecret
Prefixpk_sk_
Environmenttest or livetest or live
Length~40 characters~40 characters
Character setAlphanumericAlphanumeric
ExpiresNo (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​

OperationPublishableSecret
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​

ErrorCauseSolution
INVALID_API_KEYKey is malformed or not foundVerify key format and value
API_KEY_INACTIVEKey has been revokedGenerate new key pair
NO_STORE_ACCESSWrong store for this keyUse correct key for the store
ACCESS_DENIEDInsufficient permissionsUse 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.

Need Help?​