Authentication
API keys, sandbox and production, scopes and IP allowlists.
Send your API key in the X-Access-Token header on every request except GET /v3/ping.
curl "$API_URL/v3/account/balance" -H "X-Access-Token: $API_KEY"Sandbox and production keys
| Sandbox | Production | |
|---|---|---|
| Prefix | flx_test_ | flx_live_ |
| Money | Never charged. Balance is always 100,000 DZD. | Your real balance. |
| Operators | Simulated. See test numbers. | Real top-ups. |
| Rate limit | 60 requests per minute | 120 requests per minute |
Both keys use the same URL and the same endpoints. To know which kind of key a request used, read data.apiKey.type from GET /v3/validate rather than parsing the key.
Creating and managing keys
Open Settings → Partner API in your dashboard and use the API keys (v3) card. If you don't see the Partner API tab, contact support to enable API access for your account. You can have up to 10 active keys. For each key you choose:
- Type: Sandbox or Production.
- Scope:
READ-WRITE(default) can send top-ups.READ-ONLYcan read your balance, plans and top-ups, but any send is refused withREAD_ONLY_KEY. Use it for dashboards and reporting. - Allowed IPs: when set, requests from any other IP are refused with
IP_NOT_ALLOWED. Leave it empty to allow all IPs. Always set it for production keys.
The full key is shown once, when you create it. We only store a fingerprint of it, so a lost key cannot be recovered: revoke it and create a new one.
Keep keys secret
Call the API from your server only. Anyone with your key can spend your balance. Never ship a key in a website, a mobile app, or a public repository. If a key leaks, revoke it at once from the dashboard.
Rotating a key
- Create a new key with the same scope and allowed IPs.
- Deploy it to your servers.
- Watch the old key's last used time stop moving, then revoke it.
Revoke and disable keys from the same card. Revoking is immediate. Allow up to one minute for every server of ours to stop accepting a revoked or disabled key.
Failed attempts
After 5 failed authentications from the same IP within 15 minutes, that IP is blocked for 15 minutes and gets IP_BLOCKED, even with a valid key. INVALID_ACCESS_TOKEN errors include details.attemptsLeft.
Authentication errors
| Code | HTTP | What to do |
|---|---|---|
MISSING_ACCESS_TOKEN | 401 | Add the X-Access-Token header. |
INVALID_ACCESS_TOKEN | 401 | Check the key. It may be revoked or mistyped. |
IP_BLOCKED | 403 | Too many failures. Wait for Retry-After seconds. |
IP_NOT_ALLOWED | 403 | Add this server's IP to the key, or call from an allowed IP. |
API_DISABLED | 403 | The key is disabled, or API access is off for your account. |
ACCOUNT_DISABLED | 403 | Your account is suspended or not approved. Contact support. |
AUTH_UNAVAILABLE | 503 | We cannot check keys right now. Your key is fine: retry after Retry-After. |