Authentication

All C-Tax API endpoints require authentication using API keys. This guide explains how to authenticate your requests and manage your API credentials.

API Key Authentication

C-Tax uses Bearer token authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET https://c-tax.1809ltd.co.ke/api/v1/branches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Code Examples

JavaScript

const axios = require('axios');
 
const client = axios.create({
  baseURL: 'https://c-tax.1809ltd.co.ke/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.CTAX_API_KEY}`,
    'Content-Type': 'application/json'
  }
});
 
// Make API request
const response = await client.get('/branches');

PHP

use GuzzleHttp\Client;
 
$client = new Client([
    'base_uri' => 'https://c-tax.1809ltd.co.ke/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . env('CTAX_API_KEY'),
        'Content-Type' => 'application/json',
    ],
]);
 
$response = $client->get('branches');

Python

import requests
 
headers = {
    'Authorization': f'Bearer {os.environ["CTAX_API_KEY"]}',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    'https://c-tax.1809ltd.co.ke/api/v1/branches',
    headers=headers
)

Obtaining API Keys

API keys are generated when your client account is approved by C-Tax administrators.

Account Approval Process

1. Register - Submit your business information
2. Review - C-Tax team reviews your application
3. Approval - Upon approval, you receive your API key
4. Access - Use the API key to authenticate requests

API Key Format

API keys are unique 64-character strings:

ctax_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Environments

C-Tax provides two environments:

Use sandbox for development and testing before going live.

Client Status

Your client account must be active to make API requests. Account statuses:

Branch Context

Some endpoints require branch context. Use the X-Branch-ID header or include bhf_id in the request:

# Using header
curl -X POST https://c-tax.1809ltd.co.ke/api/v1/sales \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Branch-ID: 00" \
  -H "Content-Type: application/json" \
  -d '{"invoice_no": "INV-001", ...}'
 
# Using request body
curl -X POST https://c-tax.1809ltd.co.ke/api/v1/sales \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch_id": "00", "invoice_no": "INV-001", ...}'

Rate Limiting

API requests are rate limited to ensure fair usage:

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705329060

Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "status": "error",
  "message": "Too many requests. Please try again later.",
  "meta": {
    "retry_after": 30
  }
}

Wait for the retry_after seconds before retrying.

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "status": "error",
  "message": "Invalid API key or unauthorized access"
}

Common causes:

• Missing Authorization header
• Invalid API key format
• Expired or revoked API key
• Client account not active

403 Forbidden

Insufficient permissions:

{
  "status": "error",
  "message": "You do not have permission to access this resource"
}

Common causes:

• Accessing another client’s resources
• Branch not owned by your account
• Feature not enabled for your plan

Security Best Practices

API Key Management

1. Never expose keys - Don’t include API keys in client-side code
2. Use environment variables - Store keys in environment variables
3. Rotate regularly - Request new keys periodically
4. Limit access - Only share keys with authorized team members
5. Monitor usage - Review API logs for unusual activity

Environment Variables

# .env file
CTAX_API_KEY=ctax_live_a1b2c3d4e5f6...
CTAX_WEBHOOK_SECRET=whsec_abc123...

Server-Side Only

Always make API calls from your server, never from browsers:

// BAD - Don't do this in browser
fetch('/api/v1/sales', {
  headers: { 'Authorization': 'Bearer ctax_live_...' }
});
 
// GOOD - Call your own backend
fetch('/your-api/create-sale', {
  method: 'POST',
  body: JSON.stringify(saleData)
});
 
// Your backend then calls C-Tax API

IP Whitelisting (Optional)

For enhanced security, you can request IP whitelisting for your API key. Contact support to configure allowed IP addresses.

Testing Authentication

Verify your API key is working:

curl -X GET https://c-tax.1809ltd.co.ke/api/v1/branches \
  -H "Authorization: Bearer YOUR_API_KEY"

Expected response:

{
  "status": "success",
  "data": [...],
  "meta": {
    "total": 2,
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

User Roles and Permissions

Within your organization, users have different roles:

Role permissions affect both web interface and API access.

Session Management

API keys don’t expire but can be revoked. For web-based access, sessions are managed separately with:

• Session timeout after inactivity
• Two-factor authentication (optional)
• Email verification required

Support

If you’re having authentication issues:

1. Verify API key is correct and complete
2. Check client account status
3. Ensure proper header format
4. Review rate limit status
5. Contact support@c-tax.ke

Next Steps

• Branches API - Set up branches
• Devices API - Configure VSCU devices
• Sales API - Start processing transactions