Authentication

Both ZEST APIs (Admin and Store APIs) use the same approach to making and authenticating requests. There are two different approaches offered:

  • manually create an API key & provide it with each request over HTTPS
  • using OAuth2 (beta)

Application key

To authenticate a request using an API application key, you need to:

  1. Register the key in the ZEST administration interface.
  2. Provide the key over an HTTPS connection with each request to prove you are an authenticated user.

Registering an API Application key

To register a new key with ZEST you need to log into the administration tool, and navigate to: Preferences > Webiste Administrators > Api.

This will provide you with an interface allowing you to register a new application key:

Create Application Key

This will allow a key to be specified and access granted to specific or all API resources. Specific resources can also be set to 'deny' which prohibits access to this particular resource with the specified key.

A timeout can also be specified so access is only granted for a specific period of time.

Programatically generating new API keys

The API exposes a resource called ApiAccess. If your key grants you access to this resource, you will be able to create new API keys, using the API itself.

Making a request with an application key

Once registered you can use this key to access any allowed resources by either: * passing the key as the "username" using basic authentication, with no password (recommended); or * if for some reason you are unable to use this approach, a fallback allows you to pass it in the querystring for the request as _key=$application_key.

If requesting directly via a URL, a GET request to retrieve a product resource might look like this:

GET https://[application_key]:@www.clientwebsite.nz/API/V3/Products/[product sku]

In Postman it may look something like this:

Auth via Postman

OAuth2 (beta)

If you are creating an app and you want ZEST sites to be able to connect without a manual setup step, you can automate the process of creating an application key by implementing OAuth2. This is only really worth the effort if you need to avoid having to get customers to provide you with an API URL and application key. For one-off integration scripts, it is generally much more simple to just use the application key approach outlined above.

We (partially) implement OAuth2. This is limited availability at this point, and still has some rough edges for developers (for example, we don't implement all the normal error responses etc that a proper implementation should have). We also only implement the “Authorization Code Grant” flow which only really works for web-based applications. Contact our developer support to request a client id.

Making a request with OAuth

If you have used OAuth before, you will probably be familiar with this process:

  1. First you need a client id. Contact our developer support to set one up for you.
  2. Redirect your user to a the "authorization endpoint", by asking them to click a button or a link to connect your application to their ZEST website. The URL should be of the format:
https://www.clientwebsite.nz/api_oauth?response_type=code&client_id=$client_id&redirect_uri$redirect_uri

Where $client_id is your client id, and $redirect_uri is the full url of a page on your site that will handle the second half of the authorisation process.

  1. The user, when clicking this link, will be asked to login to their website, approve you application to access it, and ultimately they will be redirected back to your redirect_uri. However an extra cgi parameter, code will be appended to the url containing an authorization code which can be exchanged for an access token.

  2. You then send a server-side request to exchange the authorization code for an access token using whatever HTTP library you prefer. Send your server side request to request the endpoint:

https://www.clientwebsite.nz/api_oauth?grant_type=authorization_code&code=$code&redirect_uri=$redirect_uri

Where $code is the authorization code you were passed back in the code parameter described in step 3 above. The $redirect_uri needs to be exactly the same as the one you passed in the link described above or your request will be rejected.

  1. This will return JSON, something like this:
{
    "access_token": "wqr454v256v566b5652g654g5462g",
    "zeald_api_endpoint" : "https://secure.zeald.com/clientsite/API/V3",
    "token_type": "bearer"
}
  1. You can now use the access_token as an API application_key as described in the making a request section above - passing it in using basic auth (or, worst case, as a _key querystring parameter). The zeald_api_endpoint is the api endpoint you have been authorised to access. You should save these values in your database somewhere - the token does not expire (unless manually deleted), and you don't want to make the user re-authenticate every time.

Simple PHP Example

Here is some basic PHP code to give you a simple walkthrough of the process.

<html>
<body>
    <h1>OAUTH 2.0 example</h1>

<?php
// the redirect url is the url of a page on your server that's going to handle the authorisation. In this case, we'll use the current page:
$redirectTo = urlencode("https://". $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI']);

if (!$_REQUEST[code]) {
    echo '<button onclick="window.location=\'https://secure.zeald.com/zeald/api_oauth?response_type=code&client_id=zeald&redirect_uri=' . $redirectTo . '" >Start oauth</button>';
} else {
    require_once "HTTP/Request.php"; // http://pear.php.net/package/HTTP_Request/

    // now we exchange the code thats been returned to us for an access token, by doing a server side request
    // replace this with the target website url
    $endpoint = "https://www.clientwebsite.nz/api_oauth?code=" . urlencode($_REQUEST['code'])
        . "&grant_type=authorization_code&redirect_uri=" . urlencode($redirect_uri);
    $request = new HTTP_Request($endpoint);

    if (!PEAR::isError($request->sendRequest())) {
        $response = $request->getResponseBody();
    } else {
        exit('Error occured: ' . $request->getResponseBody());
    }
    $oauthResponse = json_decode($response);

    // the application key and api url are the two pieces of info you need to query the api
    $apiUrl = $oauthResponse->{zeald_api_endpoint};
    $token = $oauthResponse->{access_token};
    // @TODO - save them in your own database, and use them for all later querying

    // now to demo our new key actually works, lets try it out by printing out the orders in this website:
    // fetch the XML
    $request = & new HTTP_Request("$apiUrl/Order");
    $request->setBasicAuth($token, "");
    if (!PEAR::isError($request->sendRequest())) {
        $response = $request->getResponseBody();
    } else {
        exit('Error occured: ' . $request->getResponseBody());
    }

    // parse and output the orders:
    $parsed = simplexml_load_string($response);
    echo "<ul>";
    foreach( $parsed->Order as $order ) {
        echo "<li>" . $order->order_number . " " . $order->username . "</li>";
    }
    echo "</ul>";
}
?>

</body>
</html>