Security Best Practices

Protect your store, customers, and data with these security guidelines. Learn how to properly manage API keys, implement access controls, and secure your integration.

Key Principles

• Least Privilege — Grant only the permissions each key needs
• Defense in Depth — Layer security controls for protection
• Regular Rotation — Rotate keys periodically and after incidents

API Key Management

Create Separate Keys for Each Purpose

Environment-Specific Keys

Never share keys between environments:

# Development (.env.local)
BARECOMMERCE_API_KEY=sk_live_dev_key_here
 
# Staging (.env.staging)
BARECOMMERCE_API_KEY=sk_live_staging_key_here
 
# Production (.env.production)
BARECOMMERCE_API_KEY=sk_live_prod_key_here

⚠️ Never commit keys to version control. Add .env* to your .gitignore.

Storing Keys Securely

Use Environment Variables

// ✅ Good - read from environment
const apiKey = process.env.BARECOMMERCE_API_KEY;
 
// ❌ Bad - hardcoded key
const apiKey = 'sk_live_abc123...';

Use a Secrets Manager

For production, use services like:

• AWS Secrets Manager
• Google Secret Manager
• HashiCorp Vault

These provide encryption, access controls, and audit logging.

Server-Side Only

API keys should only be used server-side. Never expose them to browsers:

// ✅ Good - Server Component / API Route
export async function GET() {
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.BARECOMMERCE_API_KEY}` }
  });
  return Response.json(await res.json());
}
 
// ❌ Bad - Client Component
// This exposes your key in the browser!
'use client';
fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` } // NEVER DO THIS
});

Key Rotation

Rotate API keys regularly and immediately after any security incident.

Zero-Downtime Rotation

1. Create a new API key with the same scopes
2. Update your application's environment variables
3. Deploy the changes
4. Verify the new key works correctly
5. Delete the old key in the dashboard

When to Rotate

• ✅ Every 90 days (recommended schedule)
• ⚠️ Immediately if a key is accidentally exposed
• ⚠️ When an employee with access leaves
• ⚠️ After any security incident or breach

Webhook Security

Always verify webhook signatures:

import crypto from 'crypto';
 
function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
 
  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  if (!verifyWebhookSignature(req.rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
 
  // Process webhook...
  res.status(200).send('OK');
});

⚠️ Use crypto.timingSafeEqual() for signature comparison. Regular string comparison is vulnerable to timing attacks.

Data Protection

Customer Data

• Only collect data you actually need
• Implement data retention policies
• Provide data export and deletion capabilities (GDPR)
• Never log sensitive data (passwords, full card numbers)

Payment Data

• Use payment provider tokens, never handle raw card data
• Store only payment provider references (Stripe customer/payment IDs)
• Never log payment tokens or credentials

Security Checklist

• API keys stored in environment variables
• Keys never committed to version control
• Separate keys per environment (dev/staging/prod)
• Keys scoped to minimum required permissions
• API calls made server-side only
• Webhook signatures verified
• HTTPS enforced for all webhook endpoints
• Key rotation schedule established
• Audit logs monitored for suspicious activity

Related Guides

• Authentication — API keys and access control
• Webhooks — Secure webhook implementation