Authentication

All authenticated endpoints expect a Bearer API key in the Authorization header:

Authorization: Bearer <your-api-key>

Key types

Prefix	Mode	Description
pk_live_	Production	Real orders dispatched to drivers.
pk_test_	Sandbox	Test orders, fully isolated from production.

Both keys are issued for your merchant account. A request authenticated with your sandbox key behaves like production except that:

• Test data is kept fully separate from your real orders and customers
• Your wallet is not charged
• No notifications are sent to delivery partners or agents
• No outbound webhooks fire
• Test orders never reach real drivers or operations

This means you can develop and test against the real API surface with zero risk to production data or your wallet balance.

Obtaining keys

Keys are long random strings prefixed by key type:

pk_live_xxxxxxxx…   (production)
pk_test_xxxxxxxx…   (sandbox)

There are two ways to get keys:

1. From the Wasal team — request a live and/or sandbox key for your merchant account.
2. Self-service sandbox — generate your own pk_test_ key from your merchant dashboard for experimentation.

Shared demo sandbox key

To start testing without any setup, use the shared demo sandbox key available in your merchant dashboard.

Regenerating a key invalidates the previous one. If you regenerate, update every system that uses the old key immediately or its requests will start returning 401 INVALID_API_KEY.

Security guidance

• Never expose pk_live_ keys in client-side code (browser, mobile app bundles). All production calls must originate from your server.
• Store keys in environment variables or a secrets manager — never commit them to source control.
• Use the sandbox key for all development, CI, and demos.
• Rotate keys periodically and immediately if one is ever exposed.
• All traffic must be over HTTPS. Plain HTTP requests are rejected.

Authentication errors

HTTP	code	Meaning
401	MISSING_API_KEY	No Authorization: Bearer header was sent.
401	INVALID_API_KEY_FORMAT	The key does not start with pk_live_ or pk_test_.
401	INVALID_API_KEY	The key is well-formed but does not match any merchant.
403	MERCHANT_INACTIVE	The merchant account is deactivated.

See the full Error Reference.

Public endpoints (no key required)

Three endpoints are intentionally public and require no key:

• GET /integration/merchant/governorate-area — area lookup (governorates, neighborhoods, blocks…)
• GET /integration/merchant/governorate-area/civil-id — Civil ID (PACI) lookup
• GET /integration/merchant/order/track/:orderNumber — customer-facing order tracking

Everything else requires a valid Bearer key.