Authentication

The Zones APIs utilize a combination of Token API and a Subscription Key for accessing the Orders APIs. Client ID, Client Secret and Subscription Key are available on the profile page.

The parameters required for authentication are:

  • Bearer token can be generated through the provided link: Token API

  • Client ID: The unique identifier for your application.

  • Client Secret: The secret key associated with your client ID.

  • Audience / Scope: It is the name of the application and would be available in the description of API.

  • Subscription Key: A key provided to subscribers for API access.

Steps for Authentication

  1. Obtain Credentials: Ensure you have received your client ID, client secret, and subscription key from Zones through a secure delivery method.

  2. Request Token: Send a POST request to the auth server URL with the client ID, client secret, and audience/scope to obtain an access token.

  3. Include Token in Requests: Use the access token received in the Authorization header of your API requests. Additionally, include the subscription key in your headers

Create access tokens

curl --location 'https://login.microsoftonline.com/d8660806-f38d-4ca0-a6f1-8deb7cfe8971/oauth2/v2.0/token' \ 
--form 'client_id="put client id"' \ 
--form 'client_secret="put secret"' \ 
--form 'grant_type="client_credentials"' \ 
--form 'scope="put audience"'

Note: the audience should be having /.default postfix. i.e. api://58dc9673-8389-4f35-ab38-2b6c0fcd45d2/.default

The access token retrieved from this call is then passed as Authorization header as Bearer token.

Subscription key

The subscription key provided by the Zones team needs to be sent as Ocp-Apim-Subscription-Key header in all the API calls.

Example

URL: https://api.zones.com/orders-api/v1/purchase-order/{zonesOrderNumber}

Authorization: Bearer XYZ...

Ocp-Apim-Subscription-Key: ABC...

Error Handling

If authentication fails, the API will return an error response. Common errors include:

  • Invalid Client: Incorrect client ID or secret.

  • Invalid Scope: The scope is not valid or not allowed.

  • Invalid Token: The token has expired or is invalid.

  • Missing Subscription Key: The subscription key is missing, incorrect or expired.

Security Considerations

To ensure the security of your application and the API, follow these best practices:

  • Secure Storage: Always store your client secret and subscription key in a secure manner. Avoid hardcoding them in your source code. Instead, use environment variables or secure vault services to manage these sensitive pieces of information.

  • Use HTTPS: Ensure that all communications with the API use HTTPS to encrypt the transmission of credentials and other sensitive data. This prevents potential interception by malicious actors.

  • Credential Rotation: Client secrets are periodically rotated for enhanced security. Make sure to update your application with the new credentials before the current ones expire. Set up a process to handle these updates promptly to avoid service disruptions.