Authentication

Every request to the Dodo Delivery API is authenticated with an API key sent in the X-API-Key header. The API does not expose username/password endpoints — merchant accounts are managed through the merchant dashboard.

The header

X-API-Key: dk_live_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuVw

That's it — no Bearer prefix, no JWT, no refresh token. Send the key with every request.

curl https://api.dodo.co.tz/api/v1/merchant/shipments \
  -H "X-API-Key: $DODO_API_KEY"

Getting a key

1. Sign up at merchant.dodo.co.tz/register.
2. Wait for admin approval (you'll receive an email — usually within one business day).
3. Once approved, log in and go to Settings → API Keys.
4. Click Generate API Key. The key is shown once — copy it immediately.

See the Quickstart for the full onboarding walkthrough including wallet top-up.

Sandbox vs production

You get a separate key for each environment:

Prefix	Environment	Base URL
dk_test_…	Sandbox	https://sandbox.dodo.co.tz/api/v1
dk_live_…	Production	https://api.dodo.co.tz/api/v1

Sandbox keys can only call the sandbox API, and vice versa. Test phone numbers, test wallets, and simulated rider assignment are documented in the Quickstart.

Keeping your key safe

warning

Treat your API key like a password. Anyone with it can create shipments and debit your wallet.

• Never commit keys to source control. Use environment variables: DODO_API_KEY.
• Never expose keys in client-side code. The API is server-to-server — your frontend should call your backend, which calls Dodo.
• Rotate immediately if leaked. In the dashboard, click Regenerate. The old key keeps working for a short grace window (about a week) so you can roll the new one out without downtime, then it's revoked. If you suspect active abuse, contact support to revoke the old key immediately.
• Use sandbox for development and CI. Never test against production with real wallet funds.

Key lifetime

API keys are valid for up to a year from issue. We'll email you ahead of expiry so you can rotate before requests start failing with 401.

Auth errors

Status	Meaning	Fix
401	Missing or invalid X-API-Key header	Check the key value and header name
403	Merchant account not yet approved	Wait for admin approval email
403	Account suspended	Contact support

{
  "detail": "Invalid or expired API key"
}

See the full Errors reference.