Authentication & security
How to send your API key, lock it to your server IPs and stay within the rate limit.
Sending your key
Use the Bearer header. The other two forms are accepted on every merchant and legacy route, which helps when migrating from another provider.
| Header | Example | Notes |
|---|---|---|
| Authorization | Bearer ds_live_YOUR_KEY | Recommended |
| Authorization | Token ds_live_YOUR_KEY | MSORG / Adex style |
| X-API-Key | ds_live_YOUR_KEY | Alternative header |
Managing keys
Where keys live
Create, name and revoke keys in Dashboard → Developer. Sandbox keys are available right away; live keys need approved API access (Dashboard → API access).
Live and sandbox keys
Live keys start with ds_live_ and spend from your real wallet. Sandbox keys start with ds_test_ and use a test wallet. Both are shown only once, when created. If a key leaks, revoke it and create a new one.
Up to 5 active keys per environment
Use separate keys per server or environment so you can rotate one without downtime.
IP whitelist
- Manage IP whitelists in Dashboard → Developer.
- Each key can have its own list of exact IP addresses (max 20). When a key has a list, only that list applies.
- Otherwise the account-level whitelist applies to the key. It accepts IPs and CIDR ranges (max 50).
- When both are empty, requests from any IP are accepted (not recommended in production).
- Requests from other IPs are rejected with
403 IP_NOT_ALLOWED.
Rate limits
- Each API key can make 120 requests per minute. The limit is shared between the merchant API and the legacy MSORG / Adex routes.
- Going over returns
429 RATE_LIMITED— back off and retry later. - More than 20 requests with invalid keys from one IP within 5 minutes blocks that IP for 5 minutes (
429 RATE_LIMITED). - Webhook tests are limited to 10 per minute and delivery resends to 20 per minute.
Authentication errors
Checks run in this order. Each returns {"status": "failed", "code": "…", "message": "…"}.
| Code | HTTP | Meaning |
|---|---|---|
| RATE_LIMITED | 429 | Too many invalid API key attempts from your IP (more than 20 in 5 minutes). |
| UNAUTHORIZED | 401 | API key is missing, invalid, revoked or expired. |
| IP_NOT_ALLOWED | 403 | Request IP is not on the key's (or account's) whitelist. |
| ACCOUNT_SUSPENDED | 403 | Your account is suspended — contact support. |
| SANDBOX_DISABLED | 403 | A ds_test_ key was used while sandbox testing is turned off. |
| API_ACCESS_NOT_APPROVED | 403 | Live key used before API access was approved (sandbox keys are not affected). |