Authentication

Flonk KYC uses secret keys to authenticate server-side API requests. Manage your API keys in the Flonk Dashboard.

API Keys

Each key belongs to a project environment. Manage them in Dashboard → API Keys.

Never expose a secret key (sk_*) in client-side code.

Secret Key Authentication

Using the SDK (Recommended)

import { FlonkKYCServer } from '@flonkid/kyc/server';

const flonk = new FlonkKYCServer({
  secretKey: process.env.FLONK_SECRET_KEY!,
});

// SDK handles Authorization header automatically
const session = await flonk.createSession({
  clientMetadata: { email: 'user@example.com' },
});

Manual (fetch)

const response = await fetch('https://api.flonk.id/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientMetadata: { email: 'user@example.com' }
  })
});

API Versioning

The REST API is versioned by date, pinned with an optional Flonk-Version request header (the SDK sends the version it was built against automatically):

Flonk-Version: 2026-06-01

The API is additive-only within a version — new optional fields and endpoints never change behaviour for existing callers. A genuinely breaking change would ship under a new date, and requests pinned to the older date keep getting the old response shape. Omitting the header resolves to the current version. The server echoes the resolved version in the Flonk-Version response header.

Install SDK

npm install @flonkid/kyc
# or
yarn add @flonkid/kyc

Environment Variables

Configure your keys in environment variables:

# Server-side (never expose to frontend)
FLONK_SECRET_KEY=sk_live_xxxxxxxxxxxx
FLONK_API_URL=https://api.flonk.id/v1
FLONK_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

Security Best Practices

• Never expose secret keys in frontend code, git repositories, or logs
• Use environment variables to store keys
• Rotate keys regularly if you suspect a leak
• Use test keys (sk_test_*) for development

Rate Limits

If you exceed rate limits, you'll receive a 429 Too Many Requests response.