Authentication and authorization
Authenticate requests and choose API key permissions.
Send X-API-Key: <your-api-key> with every partner API request. Keep the key on your server and out of browser code, shared Postman environments and logs. Create and rotate keys in the partner portal.
Also send X-Deripay-API-Version: 2 with every request. It selects the response fields, statuses and error codes described in this guide, and the response echoes it back. Requests without it keep receiving the original format from the same URLs, so existing integrations continue to work unchanged. Check that your HTTP client sends the header before you go live.
For JSON requests, send Content-Type: application/json and Accept: application/json. Use Accept: text/event-stream for monitoring and Accept: text/csv for exports.
Your workspace must be approved and active. Select the permissions your application needs when creating its key:
| Scope | Allows |
|---|---|
authorize | Connect customers and save their default phone numbers. |
rates:read | Read markets and exchange rates. |
deposit | Create deposits and submit verification codes. |
withdraw | Start, resend and complete withdrawal verification. |
transactions:read | Read connections, balances, transactions, transfers and reports. |
transfers:write | Create, retry and dismiss Wallet–Options transfers. Available to every approved workspace. |
Save each connection_id with the customer it belongs to. Before forwarding a request from your frontend, check that the signed-in customer owns that connection. Deripay also checks that transactions and transfers belong to your integration and the supplied connection.
If you receive 401 AUTHENTICATION_REQUIRED, test the key with GET /api/corridors. If that works, check whether the customer's Deriv connection needs to be reauthorized. For 403 ACCESS_DENIED, check the key's permissions, workspace status, permitted country and connection ownership. For 503 SERVICE_UNAVAILABLE, wait before retrying and reuse the same request and idempotency key.