Skip to main content

Security

Comprehensive security guide covering authentication, encryption, compliance, and operational security.

Authentication Methods​

SmartPay supports multiple authentication mechanisms for different use cases:

API Keys

Third-party integrations

Authorization: Bearer olive_live_xxx

JWT Tokens

Admin dashboard

Authorization: Bearer eyJhbG...

HMAC Signatures

POS and partner integrations

X-API-Key-ID + X-Timestamp + X-Signature

Service Auth

Internal services

X-Service-Name + X-Service-Timestamp + X-Service-Signature

API Key Authentication​

API keys are used for third-party integrations:

curl -X GET "https://demo.api.vultlocal.com/api/v1/balance/user123" \
  -H "Authorization: Bearer olive_live_XXXXXXXXXXXXXXXX"

Key Formats​

EnvironmentPrefixExample
Productionolive_live_olive_live_abc123xyz
Sandboxolive_test_olive_test_abc123xyz

Key Scopes​

ScopeAccess
readBalance, transaction history
writeCreate payments, transfers
adminUser management, settings

JWT Authentication​

Admin dashboard uses JWT tokens:

# Login to get token
curl -X POST "https://demo.api.vultlocal.com/api/v1/admin/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@smartpay.example.com", "password": "secret"}'

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 86400
}

# Use token
curl -H "Authorization: Bearer eyJhbG..."

JWT Configuration​

# gateway/config.yaml
auth:
  jwt_secret: "${JWT_SECRET}"  # Minimum 32 characters
  jwt_expiry: 24h
  refresh_expiry: 168h
Warning

JWT secrets must be at least 32 characters. Use a cryptographically secure random generator.

HMAC Authentication​

POS terminals use HMAC-SHA256 signatures:

const crypto = require('crypto');

function generateSignature(method, path, body, timestamp, secret) {
  const payload = `${method}\n${path}\n${timestamp}\n${body}`;
  
  return crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
}

// Usage
const signature = generateSignature(
  'POST',
  '/api/v1/pos/payment',
  JSON.stringify({ amount: '150.00' }),
  new Date().toISOString(),
  'your_hmac_secret'
);

Required Headers​

HeaderDescription
X-API-Key-IDPartner or POS API key ID
X-SignatureHMAC-SHA256 signature
X-TimestampRFC3339 timestamp
Info

Signatures are valid for 5 minutes. Ensure your server clock is synchronized with NTP.

TLS Configuration​

External Traffic (TLS 1.3)​

All external traffic uses TLS 1.3:

# gateway/config.yaml
tls:
  enabled: true
  cert_file: /certs/gateway.crt
  key_file: /certs/gateway.key
  min_version: "1.3"

Internal Traffic (mTLS)​

gRPC between Gateway and Wallet-Core uses mutual TLS:

# wallet-core/config.yaml
tls:
  enabled: true
  cert_file: /certs/wallet-core.crt
  key_file: /certs/wallet-core.key
  ca_file: /certs/ca.crt
  require_client_cert: true

Certificate Rotation​

  • Rotate certificates every 90 days
  • Use automated renewal (cert-manager, Let's Encrypt)
  • Monitor certificate expiry with alerts

Secrets Management​

export JWT_SECRET=$(openssl rand -base64 32)
export DATABASE_URL="postgres://user:pass@host:5432/db"
export OPENAI_API_KEY="sk-..."
Warning

Never commit secrets to version control. Use environment variables or a secrets manager.

Rate Limiting​

Configure per-client rate limits:

# gateway/config.yaml
rate_limit:
  enabled: true
  requests_per_second: 100
  burst: 200
  by_client: true

Rate Limit Headers​

HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRequests remaining
X-RateLimit-ResetWindow reset timestamp

Security Layers​

Network Layer
  • VPC isolation for internal services
  • Firewall rules restricting access
  • Network policies in Kubernetes
  • Private subnets for databases
Transport Layer
  • TLS 1.3 for all external traffic
  • mTLS for internal gRPC communication
  • Certificate pinning for critical services
  • Regular certificate rotation
Application Layer
  • JWT/OAuth2 authentication
  • API key management with scopes
  • Rate limiting per client
  • Input validation and sanitization
Data Layer
  • Encrypted database connections
  • Encryption at rest (optional)
  • Comprehensive audit logging
  • Idempotency keys for operations

PII and Data Protection​

KYC Document Handling​

  • Documents stored in private S3 bucket
  • Access via short-lived pre-signed URLs
  • No PII in application logs
  • Encryption at rest with KMS

Data Retention​

Data TypeRetention
Transaction logs7 years
Audit logs5 years
KYC documentsPer regulation
Session data24 hours

Compliance​

Designed to support:

PCI-DSS

Payment card industry standards

GDPR

European data protection

SOC 2 Type II

Security and availability

ISO 27001

Information security management

Threat Mitigation​

ThreatMitigation
DDoS attacksRate limiting, load balancing, WAF
SQL injectionParameterized queries, input validation
Man-in-the-middleTLS/mTLS encryption
Replay attacksIdempotency keys, timestamps
Privilege escalationLeast privilege, RBAC
Credential stuffingRate limiting, account lockout

Security Checklist​

Warning

Complete before production deployment.

Infrastructure​

  • TLS/mTLS enabled on all services
  • Firewall rules configured
  • Network policies in place
  • VPC isolation for database

Application​

  • Strong JWT secret (32+ chars)
  • Rate limiting enabled
  • Input validation active
  • Audit logging enabled

Operations​

  • Monitoring and alerting
  • Regular backups
  • Incident response plan
  • Security training completed

Incident Response​

Detection

Monitor logs and alerts for suspicious activity

Containment

Isolate affected systems, revoke compromised credentials

Investigation

Analyze audit logs and transaction history

Remediation

Apply fixes, patches, and security updates

Recovery

Restore normal operations

Post-Mortem

Document findings and improve processes

Gateway Authentication

Detailed auth configuration

Deployment Guide

Production deployment