Skip to main content

​
About Zones

Zones is an IT solutions and hardware reseller. Serval connects to the Zones API to place and track orders and to read product catalogs, calling Zones’ REST API on your behalf whenever a Serval workflow runs. Authentication: A Zones API subscription key (sent as the Ocp-Apim-Subscription-Key header) plus OAuth 2.0 client credentials (Client ID, Client Secret, and a Scope). Serval exchanges the client credentials for a short-lived bearer token at Zones’ token endpoint and sends both the bearer token and the subscription key on every request. Environment: This integration targets the Zones test environment (apitest.zones.com). Data sync: On-demand only - there is no background sync or scheduled ingestion. Serval reads from and writes to Zones at the moment a Serval workflow runs.
The Zones Advance Shipment Notification (ASN) service is a separate, event-driven product: Zones pushes shipment updates to a URL you register, rather than exposing endpoints Serval calls. It is not part of this integration, which covers the Orders and Product Catalog REST APIs.

​
What the Zones integration enables

​
Get your credentials

Serval needs two things from the Zones developer portal: a subscription key and an OAuth client (Client ID, Client Secret, and Scope).
1

Sign in to the Zones developer portal

Go to developer.zones.com and sign in with your Zones developer account.
2

Copy your subscription key

Open your Subscriptions (or Profile) page and copy the subscription key for the products you need (Orders API and Product Catalog). This value is sent as the Ocp-Apim-Subscription-Key header on every request.
Treat the subscription key like a password. If it’s ever exposed, regenerate it from the portal and update the Serval connection.
3

Find your client credentials

On your Profile page, open the Environment Secrets section. Copy the Client ID, Client Secret, and the Scope (the app name used as the token scope).
The Scope is the application name shown alongside the client credentials - not a permission string. Copy it exactly as shown.

​
Connect in Serval

All four fields are required. The form flags any required field left blank, and an incomplete configuration that reaches Serval’s backend is rejected with a message beginning “Invalid Zones configuration” (for example, “subscription key is required” or “client ID is required”).
1

Enter the Subscription Key

Your Zones API subscription key from the developer portal’s Subscriptions page. Stored encrypted. When editing the connection later, it appears obfuscated - leave it unchanged to keep the stored value.
2

Enter the Client ID

The OAuth client ID from the Environment Secrets section of your Zones profile.
3

Enter the Client Secret

The OAuth client secret from the same section. Stored encrypted; obfuscated on the edit form - leave it unchanged to keep the stored value.
4

Enter the Scope

The app name used as the token scope, from the Environment Secrets section.

​
Verifying the connection

After saving, Serval runs these health checks:
  • Test Zones Connection - performs the full client-credentials token exchange, then fetches the standard catalog to confirm both the subscription key and token are valid. On success: “Successfully authenticated with Zones”. On failure: “Unable to connect to Zones. Please verify your Subscription Key, Client ID, Client Secret, and Scope are valid.”
  • List Zones Standard Catalog - confirms the Product Catalog API is reachable by fetching the standard catalog.
  • List Zones Non-Standard Catalog - confirms the Product Catalog API is reachable by fetching the non-standard catalog.

​
Gotchas and troubleshooting

Zones requires two credentials on each Orders/Catalog call: the Ocp-Apim-Subscription-Key header and an Authorization: Bearer token. Serval handles both automatically - it exchanges your Client ID, Client Secret, and Scope for a bearer token and attaches the subscription key. A 401 usually means the bearer token or client credentials are wrong; a 403 typically means the subscription key lacks access to the product being called.
The Scope field is the application name from the portal’s Environment Secrets, sent verbatim in the token request. If it doesn’t match what the portal shows, the token exchange fails and requests are rejected. Update it in Serval whenever it changes in the portal.
Zones access tokens expire about an hour after they’re issued. Serval requests a fresh token as needed, so no action is required - but a token endpoint outage surfaces as an authentication failure even when your credentials are correct.
This integration targets apitest.zones.com. Make sure the subscription key and client credentials you enter belong to the same environment.
For teams building custom automations through the generic API request action, paths already include the product prefix - for example /orders/v1/purchase-order and /catalog/v1/standards. Do not add https:// or the host; Serval routes requests to Zones automatically.
Need help? Contact support@serval.com for assistance with your Zones integration.