Authentication and API keys

Purpose#

Every call to the merchant API or the company API must carry an API key. The key identifies your account, so whatever the call does (for example creating parcels) is done as you. This page shows where to get the key, how to send it and what the API answers when something is wrong.

Who can get a key#

• Merchants: platform merchants only. A merchant who belongs to a delivery company gets a notice that the feature is for platform merchant accounts and is sent back to the dashboard.
• Delivery companies: company admins only. The Integrations and API entry appears in the company menu for admins.

What you need#

• An active account and, for a company, an active subscription. Platform-owned and merchant-owned companies are exempt from the subscription.
• A plan that includes the API feature. The super admin sets it per plan: a new merchant plan starts with the API off and a new company plan with it on. Merchant plan features are enforced only while the platform has at least one active merchant plan, and platform-owned and merchant-owned companies need no plan. When the plan lacks the feature, no key can be generated: merchants get a warning with the reason, and the company page shows a notice and disables the buttons.

Get a merchant key#

1. Open Webhook and API

   In the merchant menu, under Integration, click Webhook and API.

2. Generate the developer key

   In the Webhook keys table, find the first row. Its name is displayed in Arabic as «API للمطورين» (Developer API), even in the English interface, and its description reads "To integrate with any system or platform not listed (ERP, your app, a custom store)". If the Key column says No key, press Generate.

3. Copy the key

   The page reloads with the full key visible. Press Copy. On later visits the key is masked (first 7 and last 4 characters); press Show / hide to reveal it again.

4. Store it on your server

   Keep it in an environment variable or a secret store, never in a mobile app or in browser code.

1234

1. Your current API keys (shown masked)
2. The name of the platform or system you connect
3. Generate a new key
4. Open the API documentation

Get a company key#

1. Open Integrations and API

   Sign in as a company admin and open Integrations and API from the company menu.

2. Check the plan card

   The Company plan card shows your plan, its expiry date, its features and today's usage (API requests today).

3. Generate the key

   In the API key card press Generate API key.

4. Copy the key and the Base URL

   The key is shown in full right after generation, and afterwards masked (first 8 and last 4 characters) with an eye button to reveal it and a copy button. The Base URL is shown at the bottom of the API key card.

Send the key#

Put the key in an Authorization header with the Bearer scheme.

curl https://YOUR_DOMAIN/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

• Only this header is read. A key in the URL or in the body is ignored.
• The company API has its own key and base path /api/company/v1 (for example /api/company/v1/me).
• Add Accept-Language: en for English error messages.
• Keys have no expiry date: a key works until you renew or revoke it.

Expected result#

The call returns 200 with {"success": true, "data": ...}: for the merchant API your merchant account, plan and balances; for the company API your company, plan and usage. That proves the key works. Any other answer is explained in "What happens with a missing or wrong key".

What the prefixes mean#

What happens with a missing or wrong key#

The API runs these checks in order and stops at the first one that fails. Every answer uses the standard error envelope.

{ "success": false, "error": { "code": "invalid_key", "message": "The key is invalid or revoked. Generate a new key from the merchant dashboard." } }

Renew, revoke and protect the key#

• Renew creates a new key and the old one stops working immediately. Update every system that uses it.
• Revoke (the Cancel button; a trash icon in the merchant table) deletes the key and every system using it stops working.
• Whoever holds the key acts as your account, so renew it at once if it leaks. A merchant key can create parcels on that merchant's account, with the fees deducted from its shipping balance. A company key can read the company's merchants, couriers and parcels, create parcels for its merchants, assign couriers and change parcel statuses; the fee is taken from a merchant's balance with the company only when that merchant pays "From their balance in advance".
• The signed-in owner can reveal the full key in the panel at any time, so protect panel access as well.

Common mistakes#

• Forgetting to update your system after pressing Renew.
• Putting the key in the URL (?key=...) or in the body: 401 and unauthenticated.
• Getting 403 and plan_feature with a key generated earlier: a merchant's plan has expired or lost the API feature, or a company's plan lacks it (a company whose subscription ended gets 402 and subscription_expired). Renew the subscription or have the API feature enabled in the plan, and the same key works again.

Limits and permissions#

• Company: the key is stored on the company's owner admin account. Every company admin sees and renews the same key, and if that owner account is suspended the API answers account_inactive.
• Key generation is rate-limited: 20 requests per minute for merchants and 10 for companies.