API Credentials

The Zara 4 API uses OAuth authentication, using access tokens to grant limited access to your account. To gain access through the API, you need an API_CLIENT_ID and API_CLIENT_SECRET which you can obtain by viewing your account api credentials.

You can also use the Zara 4 API in 'sandbox' mode by using your test api credentials. This works in exactly the same way but does not count towards your account quota, and cannot access your real account data.


Authenticating using SDK

The easiest way to authenticate with the Zara 4 API is by using one of our programming SDKs.

Our programming SDKs provide helper classes that perform authentication and reauthentication with the Zara 4 API automatically.

Example authentication

// Import Zara 4 classes
use Zara4\API\Client;

// ...

$apiClient = new Client('API_CLIENT_ID', 'API_CLIENT_SECRET');
// Import Zara 4 classes
import org.zara4.api.*;

// ...

Client apiClient = new Client("API_CLIENT_ID", "API_CLIENT_SECRET");
# Import Zara 4 classes
require 'zara4'

# ...

api_client = Zara4::API::Client.new({
  'client_id'     => 'API_CLIENT_ID',
  'client_secret' => 'API_CLIENT_SECRET'
})
NODEJS CODE
PYTHON CODE
'Import Zara 4 classes'
Imports Zara4.API

'...'

Dim apiClient = new Client("API_CLIENT_ID", "API_CLIENT_SECRET")
// Import Zara 4 classes
using Zara4.API;

// ...

Client apiClient = new Client("API_CLIENT_ID", "API_CLIENT_SECRET");

Manual Authentication

You can also authenticate with the API manually without using our SDKs. To do this you will require some knowledge of OAuth as well as how to perform RESTful http requests within your chosen programming language.

To access the API you will require an access_token to authenticate your API requests. Access tokens are obtained by providing your application client_id and client_secret which can be found in your account API credentials. You will need to register to obtain API credentials.

The scope included in your authentication request specifies the permissions the returned access token will have over your account. In the example below, the generated access token will have permission to optimise images and read the account usage data. Each scope should be separated by a comma - see scopes for more.

Example OAuth Authentication Request

curl https://api.zara4.com/oauth/access_token -X POST \
  -d grant_type=client_credentials \
  -d client_id=API_CLIENT_ID \
  -d client_secret=API_CLIENT_SECRET \
  -d scope=image-processing,usage

Example Authentication Response

{
  "access_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "token_type":"Bearer",
  "expires_in":3600
}

The returned access_token can now be used for to authenticate your API requests.

The access_token will expire after a time period of expires_in (seconds), after which you should request a new access token.

Scopes

Zara 4 uses scopes to allow you to specify what permissions a generated access_token should have. This enables you to generate API access tokens with restricted access to your account.

For example, you wish to create an application in collaboration with a third party that will display your account usage data on a graph. You need to give the third party an access token that can read your usage data, but you don't want them to be able to process images using your account quota.

Scope Description
image-processing

Allow submission of images to be optimised by Zara 4.
Images submitted using the generated access_token will count towards your account quota.

usage Give access to read account usage data.
(For example, the number of requests completed this month.)