Authentication
Authenticate every request with a secret API key sent in the x-api-key header, from your server only.
Every Dolafy API request is authenticated with a secret API key. Dolafy resolves your organization from the key itself — you never pass an organization id.
API keys
Create and revoke keys from your dashboard under Developers → Keys. Keys look like this:
dlfy_live_<random_string>
- The full key is shown only once, at creation time. Store it in your secrets manager immediately; Dolafy keeps only a hash and a short prefix for display.
- Each key belongs to your organization and can only call the scopes chosen for it.
- Revoking a key takes effect immediately. Revoked keys fail authentication on the next request.
Scopes
When you create a key you choose what it can do. Give each integration its own key with only the scopes it needs: a key that only issues cards should not be able to send bank transfers.
| Scope | Allows |
|---|---|
banking:read |
GET /v1/banking/balance, GET /v1/banking/recipients, GET /v1/banking/recipients/{recipientId}, GET /v1/banking/transfers/{transferId} |
banking:write |
POST /v1/banking/recipients, PATCH /v1/banking/recipients/{recipientId}, POST /v1/banking/transfers, POST /v1/banking/transfers/{transferId}/cancel |
cards:read |
GET /v1/cards, GET /v1/cards/balance, GET /v1/activity?type=cards |
cards:write |
POST /v1/cards, and pause, unpause, limit and cancel on a card |
cards:details |
GET /v1/cards/{cardId}/details (sensitive card data). Only enable it on a key whose server really needs it. |
checkout:read |
GET /v1/checkout/products, GET /v1/checkout/products/{productId}, GET /v1/checkout/transactions, GET /v1/checkout/transactions/{transactionReference}, GET /v1/checkout/users/{userId}/sales |
checkout:write |
POST /v1/checkout/sessions, and creating, updating or deleting checkout products |
A call outside the key’s scopes returns 403 with code api_key_scope_missing and the requiredScope it needed:
{
"error": "Forbidden",
"code": "api_key_scope_missing",
"requiredScope": "banking:write",
"requestId": "4adda759-86ec-4ec5-a3da-e1edc4cc6584"
}
Scopes narrow a key; they never grant a product your organization does not have enabled. Keys created before scopes existed were given the scopes of the product they were already calling, so existing integrations keep working unchanged. The organization owner can change a key’s scopes in the dashboard at any time; the key value stays the same.
A queued transfer is sent only while the key that queued it is still active and still has banking:write. If you revoke or narrow that key first, the transfer fails with failureCode api_key_not_authorized and nothing is sent.
Expiration
New keys expire after 1 year by default. You can choose 30 days, 90 days, 1 year or no expiration when you create a key. The dashboard warns you during a key’s last 30 days; create a replacement, deploy it, then revoke the old key. An expired key fails authentication with 401 invalid_api_key.
IP allowlist
Restrict each key to the IP addresses your servers call from. We recommend it for every key, and especially for keys that can send money or read card data. In Developers → Keys, edit the key and enter up to 20 addresses or ranges (for example 203.0.113.10 or 198.51.100.0/24). IPv4 ranges must be /16 or narrower and IPv6 ranges /32 or narrower. The dashboard shows the addresses the key was recently used from.
Once a key has an allowlist, requests from any other address return 403 with code api_key_ip_not_allowed.
Sending the key
Pass your key in the x-api-key header on every request:
GET /v1/banking/balance
x-api-key: dlfy_live_...
Do not reuse internal or dashboard headers — x-api-key is the only accepted authentication header for the public API.
Call from your server
The API is designed to be called server-side:
- Browser CORS is disabled by default. Origins are only allowlisted by arrangement with Dolafy, so a public web page cannot call the API directly.
- Your API key is a secret. Never ship it in client-side code, mobile apps, or public repositories.
- Allowlist your server IP. Ask your account manager to add your outbound server IP address(es) to your organization’s allowlist. Requests from unrecognized IPs may be blocked by Dolafy’s edge security before they reach the API. You can also restrict each key to those addresses with its own IP allowlist.
Rate limits
Requests are rate limited, with stricter limits on sensitive card endpoints. Your organization’s current limits are shown in your dashboard under Developers → Keys.
If you exceed a limit, the API returns 429. Wait the number of seconds in the Retry-After header, then retry.
Access control
An API key only works for an endpoint while all of these are true:
- Your organization has API access enabled.
- Your organization has the specific product enabled (Banking, Cards, or Checkout).
- The key has the endpoint’s scope.
- The request comes from an allowed IP, if the key has an IP allowlist.
If any of these fails, the endpoint returns a 403. See Errors & Idempotency for the exact codes.