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

X-Access-Token: YOUR_API_KEY
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 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: 
curl --request GET \
  --url https://api.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: YOUR_API_KEY'

​
Successful Response

{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "key": "ea27b376-9f5c-4b09-883f-1b96cd7b541c",
      "isEnabled": true,
      "type": "SANDBOX",
      "allowedips": [],
      "scope": "READ-WRITE"
    }
  }
}

​
API Key Properties

Your API key includes the following properties:
PropertyDescription
keyYour unique API key identifier
isEnabledWhether the key is active
typeSANDBOX or PRODUCTION
allowedipsIP whitelist
scopeREAD-WRITE or READ-ONLY

​
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

{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "Access token is required"
  },
  "requestId": "req_abc123"
}

​
401 - Invalid API Key

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid",
    "details": {
      "attemptsLeft": 3
    }
  },
  "requestId": "req_abc123"
}
After 5 failed authentication attempts, your IP will be temporarily blocked for 15 minutes.

​
403 - IP Not Whitelisted

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP address 203.0.113.45 is not whitelisted for this PRODUCTION API key. Add your IP to the whitelist at https://oneclickdz.com/#/settings"
  },
  "requestId": "req_abc123"
}
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

{
  "success": false,
  "error": {
    "code": "IP_BLOCKED",
    "message": "Your IP has been temporarily blocked due to too many invalid attempts"
  },
  "requestId": "req_abc123"
}

​
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.

​
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]