Skip to main content

Authentication

VesuvioPay uses API key pairs for authentication, similar to Stripe's authentication model. This guide explains how to obtain, use, and secure your API keys.

API Key Types​

VesuvioPay provides two types of API keys that work together:

Publishable Key (Public API Key)​

  • Format: pk_test_... or pk_live_...
  • Usage: Client-side applications (web, mobile)
  • Safety: Safe to expose in frontend code
  • Permissions: Limited to read-only and cart operations (when combined with JWT)

Use Cases:

  • Fetching store configuration and branding
  • Cart operations (with customer JWT)
  • Product availability checks
  • Checkout settings retrieval

Secret Key (Private API Key)​

  • Format: sk_test_... or sk_live_...
  • Usage: Server-side applications only
  • Safety: NEVER expose in client-side code
  • Permissions: Full access to all SDK operations

Use Cases:

  • Product synchronization
  • Customer data retrieval
  • Order management
  • Webhook endpoint configuration
  • Admin operations
Security Warning

Never expose your secret key in:

  • Frontend JavaScript code
  • Mobile app code
  • Public GitHub repositories
  • Client-side configuration files
  • Browser localStorage or cookies

How to Authenticate​

Using API Keys​

Include your API key in the X-API-Key header for all requests:

curl https://api.vesuviopay.com/api/v1/customers/{customerId} \
  -H "X-API-Key: sk_test_your_secret_key_here"
// JavaScript Example
const response = await fetch(
  'https://api.vesuviopay.com/api/v1/customers/123e4567-e89b-12d3-a456-426614174000',
  {
    headers: {
      'X-API-Key': 'sk_test_your_secret_key_here',
      'Content-Type': 'application/json'
    }
  }
);
// C# Example
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "sk_test_your_secret_key_here");

var response = await client.GetAsync(
    "https://api.vesuviopay.com/api/v1/customers/123e4567-e89b-12d3-a456-426614174000"
);

Cart Operations: API Key + JWT​

Cart operations require both an API key AND a JWT token for customer authentication:

curl https://api.vesuviopay.com/api/v1/sdk/cart/{storeId} \
  -H "X-API-Key: pk_test_your_publishable_key_here" \
  -H "Authorization: Bearer customer_jwt_token_here"
// JavaScript Example with JWT
const response = await fetch(
  `https://api.vesuviopay.com/api/v1/sdk/cart/${storeId}`,
  {
    headers: {
      'X-API-Key': 'pk_test_your_publishable_key_here',
      'Authorization': 'Bearer ' + customerJwtToken,
      'Content-Type': 'application/json'
    }
  }
);
JWT Token Acquisition

Customer JWT tokens are obtained through VesuvioPay's authentication flow. Customers log in or sign up via phone verification, and VesuvioPay issues a JWT token. [DEVELOPER NOTE: Add link to authentication flow documentation when available]

API Key Management​

Obtaining API Keys​

  1. Log in to your VesuvioPay Dashboard
  2. Navigate to Settings > API Keys
  3. Click Generate New Key Pair
  4. Choose environment (Test or Live)
  5. Save your keys securely

Key Environments​

Test Environment​

  • Purpose: Development and testing
  • Keys: pk_test_... and sk_test_...
  • Data: Isolated test data, no real charges
  • Webhooks: Send to test endpoints

Production Environment​

  • Purpose: Live production use
  • Keys: pk_live_... and sk_live_...
  • Data: Real customer and transaction data
  • Webhooks: Send to production endpoints

Rotating API Keys​

For security, you should periodically rotate your API keys:

  1. Generate a new key pair in the dashboard
  2. Update your application with the new keys
  3. Deploy the changes
  4. Revoke the old keys
Best Practice

Keep both old and new keys active during deployment to avoid downtime. Revoke old keys only after confirming the new keys work.

Revoking API Keys​

If a key is compromised:

  1. Immediately revoke it in the dashboard
  2. Generate new keys
  3. Update all applications using the revoked key
  4. Monitor for unauthorized access

Revoked keys cannot be reactivated. You must generate new keys.

API Key Scopes​

Each API key is associated with a specific Store. Keys grant access only to resources within that store:

  • Products from that store
  • Customers of that store
  • Orders placed in that store
  • Webhooks configured for that store

Error Example (accessing wrong store):

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

Authentication Errors​

Common Authentication Errors​

HTTP StatusError CodeDescription
401INVALID_API_KEYAPI key not found or malformed
401API_KEY_INACTIVEAPI key has been revoked
401API_KEY_EXPIREDAPI key has expired [DEVELOPER NOTE: Expiration not currently implemented]
401INVALID_TOKENJWT token is invalid
401TOKEN_EXPIREDJWT token has expired
403ACCESS_DENIEDInsufficient permissions for this operation
403NO_STORE_ACCESSAPI key doesn't have access to the requested store

Error Response Example​

{
  "success": false,
  "message": "Invalid API key",
  "errorCode": "INVALID_API_KEY"
}

Security Best Practices​

1. Separate Keys for Environments​

Use different API keys for test and production environments. Never use production keys in development.

2. Environment Variables​

Store API keys in environment variables, not in code:

# .env file
VESUVIO_SECRET_KEY=sk_test_abc123...
VESUVIO_PUBLISHABLE_KEY=pk_test_xyz789...
// JavaScript (Node.js)
const secretKey = process.env.VESUVIO_SECRET_KEY;
// C#
var secretKey = Environment.GetEnvironmentVariable("VESUVIO_SECRET_KEY");

3. Use Secrets Management​

For production, use a secrets management service:

  • AWS Secrets Manager
  • Azure Key Vault
  • Google Cloud Secret Manager
  • HashiCorp Vault

4. Restrict API Key Access​

  • Store secret keys only on backend servers
  • Use IP whitelisting if available [DEVELOPER NOTE: IP whitelisting not currently implemented]
  • Implement key rotation policies

5. Monitor API Key Usage​

  • Monitor for unusual activity
  • Set up alerts for failed authentication attempts
  • Audit API key usage regularly

6. Least Privilege Principle​

Use publishable keys for client-side operations whenever possible. Only use secret keys when necessary.

FAQ​

Can I use the same key for multiple stores?​

No, each API key pair is tied to a specific store. If you have multiple stores, you'll need separate key pairs for each.

What happens if my secret key is leaked?​

Immediately revoke the compromised key in your dashboard and generate a new one. Monitor your account for any unauthorized activity.

How long are JWT tokens valid?​

JWT tokens expire based on your account settings. [DEVELOPER NOTE: Document token expiration duration when finalized]

Can I regenerate the same API key?​

No, each API key is unique. Once revoked, you must generate a new key pair.

Do API keys have rate limits?​

Yes, API keys are subject to rate limiting. See the Rate Limiting guide for details.

Next Steps​