Authorization

Understanding OAuth 2.0 at Zid#

PKCE is not used. Zid's authorization code grant is for confidential clients only.
Do not send code_challenge / code_verifier — they are ignored. Protect the
authorization request with the state parameter instead (see step 2).

Key Concepts in Zid's OAuth 2.0 Flow#

One value, three names. The token endpoint returns it as access_token. Send it as
X-Manager-Token (preferred) or Access-Token — the API checks for
X-MANAGER-TOKEN first and falls back to Access-Token. Never send both with different
values.

Important Requirements#

💡 Your app must run server-side because it needs to securely store the Client Secret
during this process.

💡 Almost every API request requires both the Authorization and X-Manager-Token
headers. One without the other fails.

💡 Always send Accept-Language: en (or ar) explicitly. If the header is missing or
holds any other value, Zid replies in Arabic — including error messages. Only ar and
en are recognised.

What's the difference between Authorization token and X-MANAGER-TOKEN?#

What's the difference between X-MANAGER-TOKEN and Access-Token?#

Base URIs#

💡 The latest version of our API is v1. Older versions are deprecated and should not be used.

Benefits of Using OAuth 2.0 with Zid#

Implement OAuth 2.0 in your app#

1 — Generate Client ID and Client Secret#

Use the copy icon rather than selecting the text by hand — these values are long, and a
truncated or whitespace-padded secret fails at the token exchange with a generic
"Client authentication failed".

The redirect_uri you send later must match one of the allowed redirection URLs
exactly — scheme, host, port, path, and trailing slash. A mismatch fails at the token
exchange, not at the redirect, which makes it easy to misdiagnose. See
Authorization Errors & Troubleshooting.

2 — Redirect (Ask for merchant permission)#

If nothing happens when you open the authorize URL, the merchant is probably not
logged in. Zid redirects an unauthenticated merchant to their dashboard
(…/apps/{app_id}, or the shipping-providers page for shipping apps) rather than
returning an error. Have the merchant sign in to their store first, then retry.

Changing scopes after merchants have installed your app has consequences. Adding a
scope puts every existing installation into a pending consent state until that merchant
re-approves. Endpoints covered by already-approved scopes keep working; endpoints needing
the new scope return 403 APP_PERMISSIONS_PENDING_APPROVAL. If your app holds a
wildcard token, adding a scope withholds the app entirely for that merchant until they
re-approve.

The merchant re-approves by deactivating and reactivating your app from their
dashboard. Reactivation issues a fresh token pair carrying every current scope, so you
must be ready to receive and store new tokens at that moment. See
Authorization Errors & Troubleshooting.

3 — Callback Method (Get the tokens)#

⏱️ The authorization code is valid for 10 minutes and can be used once. Exchange it
immediately in the callback request. Do not queue the exchange for a background worker,
and do not retry with the same code after a failure — request a fresh one by restarting
the flow.

Note: In all examples the payload is sent in the request body, not as query parameters.

{
  "token_type": "Bearer",
  "expires_in": 94608000,
  "authorization": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "access_token": "eyJpdiI6Ii8vZ...",
  "refresh_token": "def5020035c1f..."
}

⚠️ expires_in is a number of seconds, not a date. Newly issued Authorization
tokens are valid for 3 years (31536000 × 3 = 94608000 seconds). Still persist
now + expires_in from the response you actually received rather than hard-coding the
number — tokens issued before mid-2025 carry a shorter 1-year expiry, and the value can
change again.

Authorization token#

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API
requests without authentication will also fail — see
Authorization Errors & Troubleshooting.

X-Manager-Token (access_token)#

Pass the content of access_token under the name X-Manager-Token, together with
Authorization, on every request.

The manager token is issued with the same expiry as the Authorization token — 3 years
for newly issued tokens. Treat expires_in from the token response as authoritative for
both, and store both together.

The data returned by this endpoint must be kept in secure storage. Abusing tokens may
result in your app being blocked.

Token lifetimes#

🚨 The refresh token expires two years before the access token. This is the single most
common way Zid integrations die.

A partner who refreshes "reactively, when a request returns 401" never refreshes at
all. The access token is still perfectly valid at month 12, so no 401 ever arrives —
while the refresh token silently expires. Two years later the access token dies too, and
by then there is no way to recover the installation: the only path back is asking every
affected merchant to reinstall your app.

Refresh on a schedule, not on an error. Run a cron job that refreshes every merchant
roughly every 10 months, regardless of whether anything has failed. This is the single
most important operational rule on this page.

4 — Refresh#

Handling Errors#

When a merchant uninstalls your app we send an app.market.application.uninstall
webhook, and every token you hold for that store is revoked immediately — the
Authorization token, the refresh token, and the X-Manager-Token.

Security and Best Practices#

Sample OAuth Clients#