Authentication

All API requests to FLUID Network must be authenticated using API keys. This guide explains how to obtain, configure, and use your API credentials.

API Key Types

FLUID Network uses two types of API keys:

Key Type	Purpose	Format
Sandbox Key	Testing and development	test_sk_...
Production Key	Live transactions	live_sk_...

Security Warning:

Never commit API keys to version control or expose them in client-side code. Always store them securely using environment variables or a secrets management system.

Obtaining API Keys

To get your API keys:

1. Contact FLUID Network - Reach out to our team to register as a Payment Provider
2. Complete Onboarding - Provide required business and technical documentation
3. Receive Credentials - You'll receive:
   • Sandbox API key for testing
   • Production API key for live transactions
   • HMAC secret (optional, for enhanced security)

Contact our team at support@fluidnetwork.africa to start the onboarding process.

Authentication Methods

FLUID Network supports two authentication methods:

1. Bearer Token Authentication (Required)

All API requests must include your API key in the Authorization header using the Bearer token scheme.

Format:

Authorization: Bearer YOUR_API_KEY

Example:

curl -X GET \
  https://api.fluid-network.com/api/v1/payment-providers/banks \
  -H 'Authorization: Bearer test_sk_1234567890abcdef' \
  -H 'Content-Type: application/json'

2. HMAC Authentication (Optional)

For enhanced security, you can enable HMAC (Hash-based Message Authentication Code) authentication. This adds cryptographic signing to verify request integrity and authenticity.

When to use HMAC:

• Production environments handling sensitive transactions
• Compliance requirements for request signing
• Additional protection against man-in-the-middle attacks

Learn more about HMAC authentication.

Making Authenticated Requests

Required Headers

Every API request must include these headers:

Header	Description	Example
Authorization	Bearer token with your API key	Bearer test_sk_...
Content-Type	Request content type	application/json
Accept	Response content type	application/json

Example Request

curl -X POST \
  https://api.fluid-network.com/api/v1/payment-providers/debit-requests/charge \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "phone_number": "+233241234567",
    "bank_identifier": "ECO",
    "amount": 100.00,
    "currency": "GHS",
    "narration": "Payment for Order #12345",
    "partner_reference": "partner_tx_123456"
  }'

Implementation Notes:

When implementing authenticated requests in your application:

1. Load API Key from Environment:

   • Never hardcode API keys in your source code
   • Use environment variables or secure configuration management
   • Example: api_key = os.getenv('FLUID_API_KEY')

2. Set Required Headers:

   • Authorization: Bearer {api_key} - Your API key with Bearer scheme
   • Content-Type: application/json - For JSON request bodies
   • Accept: application/json - To receive JSON responses

3. Make HTTP Request:

   • Use POST for creating debit requests
   • Include all required fields in the JSON body
   • Handle network errors and timeouts appropriately

4. Parse Response:

   • Check HTTP status code (200 for success, 4xx/5xx for errors)
   • Parse JSON response body
   • Handle both success and error cases

Authentication Errors

401 Unauthorized

Returned when authentication fails:

{
  "success": false,
  "error": "Unauthorized",
  "details": ["Invalid API key"]
}

Common causes:

• Missing Authorization header
• Invalid or expired API key
• Using sandbox key in production (or vice versa)
• API key not properly formatted

403 Forbidden

Returned when API key is valid but lacks permission:

{
  "success": false,
  "error": "Forbidden",
  "details": ["API key does not have permission for this operation"]
}

Common causes:

• API key disabled or suspended
• IP address not whitelisted (if IP whitelisting is enabled)
• Attempting to access restricted resources

Security Best Practices

Store Keys Securely

NEVER DO THIS:

// ❌ Don't hardcode API keys
const apiKey = 'test_sk_1234567890abcdef';

// ❌ Don't commit keys to version control
API_KEY=test_sk_1234567890abcdef

DO THIS:

// ✅ Use environment variables
const apiKey = process.env.FLUID_API_KEY;

// ✅ Use secrets management
const apiKey = await secretsManager.getSecret('FLUID_API_KEY');

Environment Variables

Store API keys in environment variables:

# .env file (add to .gitignore)
FLUID_API_KEY=test_sk_1234567890abcdef
FLUID_HMAC_SECRET=your_hmac_secret_here

Separate Keys by Environment

Use different API keys for each environment:

# Development
FLUID_API_KEY=test_sk_dev_key

# Staging
FLUID_API_KEY=test_sk_staging_key

# Production
FLUID_API_KEY=live_sk_production_key

Rotate Keys Regularly

• Rotate production keys quarterly or after security incidents
• Maintain at least two active keys during rotation for zero-downtime updates
• Revoke old keys after confirming new keys work

Monitor API Key Usage

• Log all API requests with key identifiers (not the keys themselves)
• Set up alerts for unusual activity patterns
• Review API key permissions regularly

Additional Security

For enhanced security beyond API keys:

• HMAC Authentication - Add cryptographic signing to requests
• IP Whitelisting - Restrict API access by IP address
• Security Best Practices - Comprehensive security guide

Next Steps

Environments →

Learn about Sandbox vs Production

Quickstart →

Make your first API call