Security
Flonk KYC is designed with security in mind. Follow these guidelines to maintain a secure integration.
API Key Security
Never Expose Secret Keys
Secret keys should only be used server-side:
typescript// Good: Server-sideconst secretKey = process.env.FLONK_SECRET_KEY;// Bad: Client-side (NEVER do this)const secretKey = 'sk_live_xxxxx'; // Exposed in browser
Environment Variables
Store keys in environment variables, not in code:
bash# .env (never commit to git)FLONK_SECRET_KEY=sk_live_xxxxxxxxxxxxKYC_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
Add to .gitignore:
.env.env.local.env.*.local
Webhook Security
Always Verify Signatures
Every webhook request includes a signature header. Always verify it.
Using the SDK (Recommended):
typescriptimport { FlonkKYCServer } from '@flonkid/kyc/server';const flonk = new FlonkKYCServer({secretKey: process.env.FLONK_SECRET_KEY!,});// SDK handles both signature formats automaticallyconst event = flonk.webhooks.constructEvent(rawBody,req.headers['x-signature-256'],process.env.FLONK_WEBHOOK_SECRET!,);
Manual verification:
typescriptfunction verifySignature(payload: Buffer, signature: string): boolean {if (!signature?.startsWith('sha256=')) {return false;}const sigHex = signature.slice(7);const expected = crypto.createHmac('sha256', webhookSecret).update(payload).digest('hex');return crypto.timingSafeEqual(Buffer.from(sigHex),Buffer.from(expected));}
Use Raw Body
Verify against the raw request body, not parsed JSON:
typescript// NestJS@Post('webhook')handleWebhook(@Req() req: RawBodyRequest<Request>) {const isValid = verifySignature(req.rawBody,req.get('X-Signature-256'));}
Data Protection
Minimize Stored Data
Store only what you need:
typescript// Good: Store minimal dataawait db.user.update({where: { id: userId },data: {kycVerified: true,kycVerifiedAt: new Date()}});// Avoid: Storing all extracted data unnecessarily
Encrypt Sensitive Data
If storing verification data, encrypt it:
typescriptconst encryptedData = encrypt(JSON.stringify(extractedData));await db.kycData.create({data: { userId, encryptedData }});
Network Security
Use HTTPS
All API calls and webhook endpoints must use HTTPS:
typescript// Goodconst apiUrl = 'https://api.flonk.id/v1';// Badconst apiUrl = 'http://api.flonk.id/v1';
Webhook IP Allowlist
For additional security, restrict webhook endpoints to Flonk IP ranges. Contact support for current IP ranges.
Compliance
GDPR
- Inform users about KYC data collection
- Provide data deletion mechanism
- Document data retention policies
Data Retention
- Delete verification data when no longer needed
- Implement automatic data expiration
- Log all data access for audit