Skip to main content

API Key Authentication

The OneClickDz Flexy API uses API key authentication. All requests must include your API key in the request header.

Header Format

The header name is X-Access-Token (not Authorization). Make sure you use the correct header name.

API Key Types

You have access to two types of API keys:

Sandbox Key

Purpose: Testing and development - No real balance deduction - Simulated responses - Special test numbers available - Safe for development

Production Key

Purpose: Live transactions - Real balance deduction - Live operator integration - Production-ready - Use with caution

Generating API Keys

1

Login to Dashboard

Visit enterprise.oneclickdz.com and login to your account
2

Navigate to Settings

Go to Settings → API Configuration
3

Generate Keys

Click “Generate API Key” for both Sandbox and Production environments
4

Save Securely

Copy and store your keys in a secure location. You won’t be able to see them again.

Validating Your API Key

Test your API key using the validate endpoint:

Successful Response

API Key Properties

Your API key includes the following properties:

IP Whitelisting

For enhanced security, you can restrict your API keys to specific IP addresses. Each environment (Production and Sandbox) has its own independent IP whitelist.
1

Go to API Settings

Navigate to Settings → API Configuration in your dashboard
2

Add IP Addresses

Enter the specific IP addresses for each environment: - Production IP Whitelist: Controls access for your production API key - Sandbox IP Whitelist: Controls access for your sandbox API key - Leave empty to allow all IP addresses
3

Save Changes

Click “Update IP Whitelist” to apply the changes
When IP whitelist contains addresses, only those specific IPs will be allowed. Requests from other IPs will be rejected with a 403 error.

IP Whitelist Format

Add specific IP addresses to the whitelist, one per line:
  • 203.0.113.45 - Allows only this specific IP address
  • 198.51.100.23 - Another specific IP address
Leave the whitelist empty to allow all IP addresses (default behavior). Add IPs to enable restrictions.

Key Scopes

API keys can have different access levels:

READ-WRITE (Default)

Full access to all operations:
  • View balance and transactions
  • Send top-ups
  • Place orders
  • Check status

READ-ONLY

Limited to read operations:
  • View balance and transactions
  • Check top-up status
  • List orders
  • Cannot create new transactions
Use READ-ONLY keys for reporting dashboards or analytics tools that shouldn’t modify data.

Error Responses

400 - Missing API Key

401 - Invalid API Key

After 5 failed authentication attempts, your IP will be temporarily blocked for 15 minutes.

403 - IP Not Whitelisted

The error response includes your current IP address and the environment (SANDBOX or PRODUCTION) to help you quickly identify which whitelist needs updating.

403 - IP Blocked

Security Best Practices

  • Never commit API keys to version control
  • Use environment variables or secret management systems
  • Rotate keys periodically
  • Use different keys for different environments
  • Always use HTTPS endpoints - Never send API keys over HTTP - Verify SSL certificates
  • Whitelist only necessary IP addresses - Use specific IPs instead of broad ranges - Update whitelist when infrastructure changes
  • Track API key usage regularly - Set up alerts for unusual activity - Review access logs - Revoke compromised keys immediately
  • Use READ-ONLY keys where possible
  • Create separate keys for different services
  • Implement least privilege principle

Key Rotation

It’s recommended to rotate your API keys periodically:
1

Generate New Key

Create a new API key from your dashboard
2

Update Application

Deploy your application with the new key
3

Verify

Test that the new key works correctly
4

Revoke Old Key

Once verified, revoke the old key from your dashboard
Rotate keys at least every 90 days for enhanced security.

Bill Payment API keys

Bill Payment is part of the v3 API, not a separate one. The key rules above apply to it too — most importantly the IP whitelist. If a whitelist is configured on your key, a Bill Payment call from an address outside it is refused with 403 IP_NOT_ALLOWED, and a key with the API switched off is refused with 403 API_DISABLED.
The Bill Payment API uses the same X-Access-Token header on the same host, so a partner already integrated with Flexy needs no new credential and no new base URL. Two things are worth restating. The endpoints live under /v3/bills. https://api.oneclickdz.com/v3/bills/..., alongside the mobile, internet and gift-card endpoints you already call. The environment belongs to the key. Each Bill Payment key is bound to exactly one environment, SANDBOX or PRODUCTION. It is a property of the key we issue, not something encoded in its text.
Never derive the environment from the key string or from a prefix. The only reliable statement is apiKey.type, returned by GET /v3/validate.
Assert this at start-up and fail the boot sequence if the key is not the one that deployment expects — it is the cheapest protection against shipping a production key into a test environment, or the reverse. Two authentication failures to tell apart:

Validate Access Token

The endpoint reference

Sandbox Testing

Testing, then switching to a production key

Need Help?

If you’re having authentication issues:
  1. Verify your API key is correct
  2. Check that you’re using the correct header name (X-Access-Token)
  3. Ensure your IP is whitelisted (if enabled)
  4. Check the API status at status.oneclickdz.com
  5. Contact support at [email protected]