Authentication

All Cashfin Business API requests require authentication using your Client Secret. This guide explains how to authenticate your requests securely.

Client Secret Authentication

The Cashfin Business API uses a simple token-based authentication. Include your Client Secret directly in the Authorization header of every request.

Authorization: cs_xxxxxxxxxxxxxxxxxxxx

Simple Authentication

Cashfin uses a single Client Secret for authentication. There is no separate API key or secret pair - just your Client Secret in the Authorization header.

Security Note

• Never expose your Client Secret in client-side JavaScript or mobile apps
• Store credentials in environment variables or secure secret management systems
• Rotate your API keys periodically

Getting Your Client Secret

Step 1: Access API Settings

1. Log in to your Cashfin Business Dashboard
2. Navigate to Settings → API
3. Click Create API Credentials

Step 2: Configure Your API Access

When creating API credentials, you can configure the following:

Setting	Description
Name	A friendly name for your API credentials (e.g., "Production API", "WooCommerce Integration")
Type	The type of integration (e.g., "ecommerce", "custom")
Webhook URL	Optional: URL to receive webhook notifications

Full Access

API credentials have full access to all API endpoints for your business. Each Client Secret can perform all operations without granular permission configuration.

Step 3: Copy Your Client Secret

After creation, you'll receive:

• Client ID - Your unique identifier (for reference only)
• Client Secret - Your authentication token (use this in the Authorization header)

Critical

Your Client Secret is only shown once during creation. Store it securely immediately.

Authentication Examples

Basic Request

cURL

curl -X GET "https://api.cashfin.africa/business/product/list" \
  -H "Authorization: cs_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

JavaScript/Node.js

const clientSecret = process.env.CASHFIN_CLIENT_SECRET;

const response = await fetch(
  "https://api.cashfin.africa/business/product/list",
  {
    headers: {
      Authorization: clientSecret,
      "Content-Type": "application/json",
    },
  }
);

PHP

<?php
$clientSecret = getenv('CASHFIN_CLIENT_SECRET');

$options = [
  'http' => [
    'header' => "Authorization: {$clientSecret}\r\n" .
                "Content-Type: application/json\r\n"
  ]
];

$context = stream_context_create($options);
$result = file_get_contents(
  'https://api.cashfin.africa/business/product/list',
  false,
  $context
);

Python

import os
import requests

client_secret = os.environ.get('CASHFIN_CLIENT_SECRET')

response = requests.get(
    'https://api.cashfin.africa/business/product/list',
    headers={
        'Authorization': client_secret,
        'Content-Type': 'application/json'
    }
)

Authentication Errors

When authentication fails, the API returns a 401 Unauthorized response:

{
  "success": false,
  "message": "Unauthorized access!"
}

Common Authentication Issues

Error	Cause	Solution
Missing header	Authorization header not provided	Add the header to your request
Invalid key	Client Secret is incorrect or malformed	Verify your Client Secret
Inactive key	API key has been deactivated	Reactivate or generate a new API key
Business inactive	Your business account is not active	Contact support

Caching & Performance

The Cashfin Business API caches authentication data for improved performance:

• Valid authentication is cached for up to 1 hour
• Changes to API keys may take up to 1 hour to propagate
• Cache is automatically invalidated when keys are rotated

Security Best Practices

1. Use Environment Variables

# .env file (never commit to version control)
CASHFIN_CLIENT_SECRET=cs_xxxxxxxxxxxxxxxxxxxx

2. Implement Key Rotation

Rotate your Client Secret periodically:

1. Create new API credentials
2. Update your application to use the new Client Secret
3. Revoke the old credentials after confirming the new one works

3. Monitor API Usage

Track your API usage in the dashboard to detect unusual activity:

• Unexpected request volumes
• Requests from unfamiliar locations
• Failed authentication attempts

4. Use HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected.

• Only requests from those IPs will be authenticated
• Leave empty to allow requests from any IP