Security Reference

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

Authentication Methods

OLIVE supports multiple authentication mechanisms for different use cases:

API Keys

Third-party integrationsAuthorization: Bearer olive_live_xxx

JWT Tokens

Admin dashboardAuthorization: Bearer eyJhbG...

HMAC Signatures

POS and partner integrationsX-API-Key-ID + X-Timestamp + X-Signature

Service Auth

Internal servicesX-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

Environment	Prefix	Example
Production	`olive_live_`	`olive_live_abc123xyz`
Sandbox	`olive_test_`	`olive_test_abc123xyz`

Key Scopes

Scope	Access
`read`	Balance, transaction history
`write`	Create payments, transfers
`admin`	User 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@olive.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

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

Header	Description
`X-API-Key-ID`	Partner or POS API key ID
`X-Signature`	HMAC-SHA256 signature
`X-Timestamp`	RFC3339 timestamp

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

Environment Variables
Kubernetes Secrets
HashiCorp Vault

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

kubectl create secret generic olive-secrets \
  --from-literal=jwt-secret=$(openssl rand -base64 32) \
  --from-literal=db-password=secret \
  -n olive

vault kv put secret/olive \
  jwt_secret=$(openssl rand -base64 32) \
  db_password=secret

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

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	Window 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 Type	Retention
Transaction logs	7 years
Audit logs	5 years
KYC documents	Per regulation
Session data	24 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

Threat	Mitigation
DDoS attacks	Rate limiting, load balancing, WAF
SQL injection	Parameterized queries, input validation
Man-in-the-middle	TLS/mTLS encryption
Replay attacks	Idempotency keys, timestamps
Privilege escalation	Least privilege, RBAC
Credential stuffing	Rate limiting, account lockout

Security Checklist

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

Architecture

Deployment

​Security Reference

​Authentication Methods

API Keys

JWT Tokens

HMAC Signatures

Service Auth

​API Key Authentication

​Key Formats

​Key Scopes

​JWT Authentication

​JWT Configuration

​HMAC Authentication

​Required Headers

​TLS Configuration

​External Traffic (TLS 1.3)

​Internal Traffic (mTLS)

​Certificate Rotation

​Secrets Management

​Rate Limiting

​Rate Limit Headers

​Security Layers

​PII and Data Protection

​KYC Document Handling

​Data Retention

​Compliance

PCI-DSS

GDPR

SOC 2 Type II

ISO 27001

​Threat Mitigation

​Security Checklist

​Infrastructure

​Application

​Operations

​Incident Response

​Related

Gateway Authentication

Deployment Guide

Security Reference

Authentication Methods

API Key Authentication

Key Formats

Key Scopes

JWT Authentication

JWT Configuration

HMAC Authentication

Required Headers

TLS Configuration

External Traffic (TLS 1.3)

Internal Traffic (mTLS)

Certificate Rotation

Secrets Management

Rate Limiting

Rate Limit Headers

Security Layers

PII and Data Protection

KYC Document Handling

Data Retention

Compliance

Threat Mitigation

Security Checklist

Infrastructure

Application

Operations

Incident Response

Related