API Keys

API keys are the primary method of authentication for the FLUID Network API. Every API request must include a valid API key in the Authorization header.

Overview

API keys serve as the foundation of FLUID's authentication system. They identify your organization and grant access to specific API endpoints based on your account type (Payment Provider or Bank).

Key Features

• Unique Identification: Each API key is unique to your organization
• Bearer Token Authentication: Standard OAuth 2.0 Bearer token format
• Environment-Specific: Separate keys for sandbox and production
• Revocable: Keys can be rotated or revoked at any time
• Rate Limited: Each key has associated rate limits

Getting Your API Keys

Step 1: Contact FLUID Network

To obtain API keys, contact our integration team:

• Email: integrations@fluidnetwork.africa
• Subject: "API Key Request - [Your Organization Name]"

Step 2: Provide Required Information

Include the following in your request:

• Organization legal name
• Contact person name and email
• Integration type (Payment Provider or Bank)
• Intended use case
• Expected transaction volume
• Webhook URL (for receiving notifications)

Step 3: Receive Credentials

You'll receive:

• Sandbox API Key: For testing and development
• Production API Key: For live transactions (after sandbox testing)
• Secret Key: For HMAC authentication (if enabled)
• Documentation Access: Link to this developer portal

Using API Keys

Basic Authentication

Include your API key in the Authorization header of every request:

curl https://api.fluid-network.com/api/v1/payment-providers/banks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Request Examples

# List available banks
curl https://api.fluid-network.com/api/v1/payment-providers/banks \
  -H "Authorization: Bearer flpk_live_abc123xyz456" \
  -H "Content-Type: application/json"

Implementation Notes:

• Use standard HTTP client library in your programming language
• Set the Authorization header with format Bearer YOUR_API_KEY
• Set Content-Type: application/json for all requests
• Handle response status codes (200 = success, 401 = unauthorized)
• Parse JSON response body for data

API Key Formats

API keys follow a specific format to identify the environment and account type:

Payment Provider Keys

• Sandbox: flpk_test_[random_string]
• Production: flpk_live_[random_string]

Example: flpk_live_abc123xyz456def789ghi012

Bank Keys

• Sandbox: flbk_test_[random_string]
• Production: flbk_live_[random_string]

Example: flbk_live_xyz789abc456def123ghi890

Key Prefix Validation

Always validate that you're using the correct key prefix for your environment:

• _test_ keys only work in sandbox
• _live_ keys only work in production

Key Management Best Practices

Secure Storage

DO:

• Store API keys in environment variables
• Use secret management services (AWS Secrets Manager, HashiCorp Vault)
• Encrypt keys at rest
• Use different keys for different environments

DON'T:

• Hardcode keys in source code
• Commit keys to version control
• Share keys via email or chat
• Use production keys in development

Example: Environment Variables

# .env file (never commit this file!)
FLUID_API_KEY=flpk_live_abc123xyz456
FLUID_SECRET_KEY=secret_xyz789abc456
FLUID_WEBHOOK_URL=https://yourdomain.com/webhooks/fluid

Implementation Notes:

• Store credentials in environment variables, not in code
• Use .env file for local development (add to .gitignore)
• Use your language's environment variable access pattern:
  • PHP: getenv('FLUID_API_KEY') or $_ENV['FLUID_API_KEY']
  • Python: os.getenv('FLUID_API_KEY')
  • Node.js: process.env.FLUID_API_KEY
  • Ruby: ENV['FLUID_API_KEY']
• Use dotenv libraries to load .env files automatically
• In production, use secret management services (AWS Secrets Manager, HashiCorp Vault, etc.)

Key Rotation

Rotate your API keys regularly to maintain security:

1. Request New Key: Contact FLUID support to generate a new key
2. Update Configuration: Add the new key to your environment
3. Deploy Changes: Roll out the new key to all services
4. Monitor: Verify requests are working with the new key
5. Revoke Old Key: Request revocation of the old key after 24-48 hours

Recommended Rotation Schedule:

• Development: Every 6 months
• Production: Every 3 months
• After Security Incident: Immediately

Error Responses

Invalid API Key

{
  "success": false,
  "error": {
    "code": 1401,
    "message": "Unauthorized",
    "category": "authentication"
  },
  "details": "Invalid or missing API key"
}

Expired API Key

{
  "success": false,
  "error": {
    "code": 1401,
    "message": "Unauthorized",
    "category": "authentication"
  },
  "details": "API key has been revoked or expired"
}

Missing Authorization Header

{
  "success": false,
  "error": {
    "code": 1401,
    "message": "Unauthorized",
    "category": "authentication"
  },
  "details": "Authorization header is required"
}

Testing Your API Key

Use this simple test to verify your API key is working:

curl https://api.fluid-network.com/api/v1/payment-providers/banks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Implementation Notes:

• Replace YOUR_API_KEY with your actual API key
• Test with sandbox key first (flpk_test_... or flbk_test_...)
• Successful response returns HTTP 200 with JSON data
• Failed authentication returns HTTP 401 with error details
• Verify response parsing in your HTTP client library

Expected Response (HTTP 200):

{
  "success": true,
  "data": [
    {
      "identifier": "EXB",
      "name": "Example Bank Ghana",
      "country": "GH",
      "currency": "GHS",
      "active": true
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

Rate Limits

Each API key has associated rate limits. See Rate Limiting Guide for details.

Default Limits

Environment	Endpoint Type	Limit
Production	Charge endpoint	1000 requests/minute
Production	Banks/Lookup	200 requests/minute
Sandbox	All endpoints	100 requests/minute

Next Steps

• HMAC Authentication - Add signature-based security
• IP Whitelisting - Restrict access by IP address
• Security Best Practices - Comprehensive security guide
• Quickstart Tutorial - Build your first integration

Support

Having trouble with API keys?

• Email: support@fluidnetwork.africa
• Documentation: https://fluidnetwork.africa/docs