Flonk
Flonk Docs

Security

Security best practices for KYC integration

Last updated: 8/19/2026
5 min read

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:

// Good: Server-side
const secretKey = process.env.FLONK_SECRET_KEY;
// Bad: Client-side (NEVER do this)
const secretKey = 'sk_live_xxxxx'; // Exposed in browser
typescript

Environment Variables

Store keys in environment variables, not in code:

# .env (never commit to git)
FLONK_SECRET_KEY=sk_live_xxxxxxxxxxxx
KYC_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
bash

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):

import { FlonkKYCServer } from '@flonkid/kyc/server';
const flonk = new FlonkKYCServer({
secretKey: process.env.FLONK_SECRET_KEY!,
});
// SDK handles both signature formats automatically
const event = flonk.webhooks.constructEvent(
rawBody,
req.headers['x-signature-256'],
process.env.FLONK_WEBHOOK_SECRET!,
);
typescript

Manual verification:

function 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)
);
}
typescript

Use Raw Body

Verify against the raw request body, not parsed JSON:

// NestJS
@Post('webhook')
handleWebhook(@Req() req: RawBodyRequest<Request>) {
const isValid = verifySignature(
req.rawBody,
req.get('X-Signature-256')
);
}
typescript

Data Protection

Minimize Stored Data

Store only what you need:

// Good: Store minimal data
await db.user.update({
where: { id: userId },
data: {
kycVerified: true,
kycVerifiedAt: new Date()
}
});
// Avoid: Storing all extracted data unnecessarily
typescript

Encrypt Sensitive Data

If storing verification data, encrypt it:

const encryptedData = encrypt(JSON.stringify(extractedData));
await db.kycData.create({
data: { userId, encryptedData }
});
typescript

Network Security

Use HTTPS

All API calls and webhook endpoints must use HTTPS:

// Good
const apiUrl = 'https://api.flonk.id/v1';
// Bad
const apiUrl = 'http://api.flonk.id/v1';
typescript

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