OVERVIEW

Authentication

Flowwithlit uses two types of credentials depending on who is calling the API: API keys for merchant-to-server calls, and JWT tokens for user-logged-in browser sessions.

API Keys

You get four API keys from the Developer API dashboard — two for test mode, two for live mode — plus one Webhook Secret shared across both modes:

Key	Prefix	Where to use it
Public Key (Test)	`flw_pub_test_`	Browser / JavaScript — safe to expose. Passed to `FlowPay.init()`
Secret Key (Test)	`flw_sec_test_`	Server-side only. Verifies transactions, accesses protected endpoints.
Public Key (Live)	`flw_pub_live_`	Browser / JavaScript — for real payments in production
Secret Key (Live)	`flw_sec_live_`	Server-side only. Never put in frontend code.
Webhook Secret	`whsec_`	Server-side only. Verifies the `X-Flowwithlit-Signature` header on incoming webhook POSTs — see Receiving Webhooks. Shown as "Webhook Secret Hash" under the Webhooks section of your dashboard, not next to the API keys.

Using Your Secret Key

Pass the secret key as a Bearer token in the Authorization header:

$ch = curl_init('https://api.flowwithlit.com/v1/transaction/verify/' . $ref);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('FLW_SECRET_KEY'),
        'Content-Type: application/json',
    ],
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.flowwithlit.com/v1/transaction/verify/' + ref, {
  headers: {
    'Authorization': `Bearer ${process.env.FLW_SECRET_KEY}`,
    'Content-Type':  'application/json',
  }
});
const data = await res.json();

curl https://api.flowwithlit.com/v1/transaction/verify/FLW_TXN_ABCD1234 \
  -H "Authorization: Bearer flw_sec_test_YOUR_KEY"

Storing Keys Securely

Always read keys from environment variables — never hardcode them in source files:

# .env  — NEVER commit this file to git
FLW_PUBLIC_KEY=flw_pub_test_xxxxxxxxxxxxxxxxxxxx
FLW_SECRET_KEY=flw_sec_test_xxxxxxxxxxxxxxxxxxxx
FLW_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx

<?php
// Using vlucas/phpdotenv (composer require vlucas/phpdotenv)
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$secretKey = getenv('FLW_SECRET_KEY');

// OR without a library (PHP >= 8):
// $secretKey = $_ENV['FLW_SECRET_KEY'];

// npm install dotenv
require('dotenv').config();

const secretKey = process.env.FLW_SECRET_KEY;
const publicKey = process.env.FLW_PUBLIC_KEY;

import os
from dotenv import load_dotenv   # pip install python-dotenv

load_dotenv()

SECRET_KEY  = os.getenv('FLW_SECRET_KEY')
PUBLIC_KEY  = os.getenv('FLW_PUBLIC_KEY')

🚨

Add .env to your .gitignore file so it's never committed to version control. If you accidentally expose a secret key, rotate it immediately from your Developer API dashboard.

Key Rotation

You can rotate your API keys at any time from the Developer API dashboard → Rotate Keys. The old keys stop working immediately. Update your server's environment variables before rotating.

Inline Checkout →

Use your public key to accept payments on your site.

Verify Transactions →

Use your secret key to confirm payments server-side.