Security & Compliance

Understanding NextAPI's security framework and compliance requirements for building secure payment applications.

Security Overview

NextAPI implements multiple layers of security to protect your payment operations:

Application Security
├── Authentication (API Keys, OAuth)
├── Authorization (Role-based Access)
├── Encryption (TLS, Data at Rest)
├── Audit Logging
└── Compliance (PCI-DSS, Data Privacy)

Authentication Methods

API Keys

The primary authentication method for server-side operations:

// Sandbox
const apiKey = 'sk_test_1234567890abcdef';

// Production
const apiKey = 'sk_live_1234567890abcdef';

// Usage
const response = await fetch('https://api.nextapi.com/v1/account', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

OAuth 2.0

For user authorization and delegated access:

// Authorization Code Flow
GET https://auth.nextapi.com/oauth/authorize?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  scope=read+write&
  state=random_string

// Exchange code for access token
POST https://auth.nextapi.com/oauth/token
{
  "grant_type": "authorization_code",
  "code": "auth_code_here",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Data Encryption

In Transit (TLS)

• All API calls use HTTPS with TLS 1.2+
• Certificate pinning available for mobile apps
• HSTS headers enforced

At Rest

• Sensitive data encrypted using AES-256
• Database encryption at rest
• Key management with hardware security modules

Authorization & Permissions

Role-Based Access Control (RBAC)

Role	Permissions	Use Case
Owner	Full access	Platform administrators
Admin	Manage wallets, payouts	Business operators
Operator	Create payouts, view reports	Daily operations
Viewer	Read-only access	Auditors, reporting

Scopes for OAuth

Scope	Permissions	Description
read	View operations	Read wallets, transactions
write	Create operations	Create payouts, payment links
admin	Admin operations	Manage wallets, users
webhooks	Webhook management	Configure webhooks

Compliance Standards

PCI-DSS Compliance

• Level 1 Service Provider: Highest certification level
• Tokenization: Card data replaced with secure tokens
• Secure Storage: No raw card data stored
• Regular Audits: Quarterly security scans, annual assessments

Data Privacy

• GDPR Compliant: EU data protection regulations
• Data Minimization: Only collect necessary data
• Right to Erasure: Data deletion capabilities
• Consent Management: Explicit user consent required

Financial Regulations

• AML/KYC: Anti-money laundering and know-your-customer
• Transaction Monitoring: Suspicious activity detection
• Reporting Requirements: Regulatory transaction reporting
• Sanctions Screening: OFAC and international sanctions

Security Best Practices

API Key Management

// Environment variables (recommended)
const apiKey = process.env.NEXTAPI_API_KEY;

// Never hardcode keys
const bad = 'sk_live_1234567890abcdef'; // DON'T DO THIS

// Use key management services
const apiKey = await secretsManager.getSecret('nextapi-api-key');

Request Signing

For high-security operations, sign requests with HMAC:

const crypto = require('crypto');

function signRequest(method, url, body, secret) {
  const timestamp = Math.floor(Date.now() / 1000);
  const message = `${method}\n${url}\n${timestamp}\n${JSON.stringify(body)}`;
  
  const signature = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  
  return {
    'X-Signature': signature,
    'X-Timestamp': timestamp
  };
}

Webhook Security

// Verify webhook signatures
function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === `sha256=${expectedSignature}`;
}

Audit and Monitoring

Audit Logs

All sensitive operations are logged:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "user_id": "user_123",
  "action": "payout_created",
  "resource_id": "payout_456",
  "ip_address": "192.168.1.100",
  "user_agent": "NextAPI-JS/1.0.0"
}

Security Monitoring

• Real-time alerts: Suspicious activity notifications
• Rate limiting: Prevent abuse and attacks
• Anomaly detection: Machine learning-based threat detection
• IP whitelisting: Restrict access by IP address

Data Handling Guidelines

Sensitive Data Classification

Classification	Data Type	Handling Requirements
Highly Sensitive	API keys, passwords	Encrypted, access logs disabled
Sensitive	Wallet balances, transaction amounts	Encrypted, audit logged
Personal Data	Names, emails, phone numbers	Encrypted, GDPR compliant
Operational Data	Transaction IDs, timestamps	Standard security

Data Retention

• Transaction data: 7 years (regulatory requirement)
• Personal data: As per user consent and GDPR
• Audit logs: 1 year for security investigations
• API logs: 90 days for troubleshooting

Security Checklist

Development

• Use environment variables for secrets
• Implement proper error handling (don't expose sensitive data)
• Validate all input parameters
• Use HTTPS for all communications
• Implement rate limiting

Production

• Regularly rotate API keys
• Monitor audit logs
• Set up security alerts
• Perform regular security assessments
• Keep dependencies updated

Compliance

• Understand applicable regulations
• Implement data retention policies
• Handle user data requests promptly
• Maintain compliance documentation
• Regular compliance training

Incident Response

Security Incident Types

1. Data Breach: Unauthorized access to sensitive data
2. API Key Compromise: Stolen or exposed API keys
3. Fraudulent Activity: Suspicious transactions
4. Service Disruption: DDoS attacks or system failures

Response Procedures

1. Detection: Automated monitoring and alerting
2. Assessment: Impact analysis and risk evaluation
3. Containment: Isolate affected systems
4. Resolution: Fix vulnerabilities and restore services
5. Notification: Inform affected parties and regulators
6. Post-mortem: Document lessons learned

Related Concepts

• [Understanding Your Wallet Structure](./understanding-your-wallet-structure
• [IDs, Reference IDs, and Idempotency](./ids-reference-ids-idempotency
• [Securely Receive and Verify Webhooks](../guides/how-to/securely-receive-and-verify-webhooks