Skip to main content

Authentication

All Cashless API requests require authentication via API key credentials.

API Key format​

Include your credentials in the Authorization header:

Authorization: ApiKey YOUR_KEY:YOUR_SECRET

The header value is the literal string ApiKey followed by a space, then your key and secret joined by a colon.

Getting your credentials​

API keys are created in the Cashless merchant dashboard at admin.cashless.co.tz. Each key pair consists of:

  • API Key -- A public identifier for your account
  • API Secret -- A private secret used to authenticate requests

Security best practices​

  • Never expose your API secret in client-side code. All API calls should be made from your server.
  • Use environment variables to store credentials, not hardcoded strings.
  • Use separate keys for sandbox and production environments.
  • Rotate keys if you suspect they've been compromised.

Example​

# Store credentials in environment variables
export CASHLESS_API_KEY="your_key_here"
export CASHLESS_API_SECRET="your_secret_here"

# Use them in requests
curl -X POST https://api.cashless.co.tz/api/v3/bills/create \
  -H "Authorization: ApiKey ${CASHLESS_API_KEY}:${CASHLESS_API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "reference": "test-001"}'

Error responses​

If authentication fails, you'll receive:

{
  "error": "Invalid api key or api secret"
}

Verify that:

  1. The header format is exactly ApiKey key:secret (note the space after ApiKey)
  2. You're using the correct key pair for the environment (live vs sandbox)
  3. Your credentials haven't been revoked