Authentication
Scope API access to your merchant and keep credentials on your server.
Send the API key
All merchant API endpoints require X-API-Key. A key identifies its merchant; do not send a merchant ID in payment requests.
GET /api/v1/balance HTTP/1.1
X-API-Key: <your-server-api-key>Merchant browser sessions are separate from API keys. Do not use a portal cookie or password as an API credential.
Available permissions
| Scope | Allows |
|---|---|
balances:read | Read merchant balances |
collections:write | Request an STK push |
collections:read | Read collection status |
disbursements:write | Request a payout |
disbursements:read | Read payout status |
Read permission does not imply write permission. Grant payout creation only to servers that need it. Merchant-managed keys cannot request wildcard or legacy Deriv permissions.
Create and revoke keys
In Developers → API keys, give each key a descriptive name and choose its permissions. Creating or revoking a key requires your current merchant password.
Up to 20 managed keys may be active at once. The dashboard lists active keys first, followed by recent revoked keys, up to 100 records. It does not expose existing third-party integration keys managed outside the portal.
A new secret is shown once. If you lose it before saving, revoke that key and create another.
Rotate without downtime
- Create a replacement with only the required scopes.
- Deploy it to the application that uses the old key.
- Verify successful API requests.
- Revoke the old key.
After revocation, subsequent authentication checks reject the key. A request authenticated before revocation may still finish. Payments already accepted continue processing.
Handle authentication failures
A missing, invalid, or revoked key returns HTTP 401. A key without the required scope returns HTTP 403. Replace or correct credentials before retrying; repeated retries do not resolve an authentication failure.
Protect your credentials
Keep API keys in server-side secret storage. Never include them in browser bundles, mobile apps, repository files, URLs, analytics events, or application logs. Treat a leaked key as compromised and revoke it.