Skip to main content

Authentication and Authorization

Summary​

  1. Authentication and Authorization

  2. Get an Access Token

  3. cURL Example

    3.1 Postman Example

    3.2 Sample Response JSON

  4. Access Token for S2S Endpoint Requests

    4.1 cURL Example

  5. Customer code and Visitor code into Access Token

    5.1 cURL Example (Request for OAuth S2S token with User and Customer code)

1. Authentication and Authorization​

For all API requests you will need to authenticate your store.

The Zakeke REST API uses the OAuth 2.0 protocol to authorize calls. OAuth is an open standard that many companies use to provide secure access to protected resources.

When you create an API Key, Zakeke generates a set of OAuth client ID and secret credentials for your Merchant Web Site for live environment. You pass these credentials in the Authorization header in a get Access Token request.

In exchange for these credentials, the Zakeke authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.

The Access-Token field in the get access token response contains a bearer token, indicated by the token_type of Bearer:


{
    "access-token": "Your-Access-Token",
    "token_type": "Bearer",
    "expires_in": 32398
}

Include this bearer token in API requests in the Authorization header with the Bearer authentication scheme.

This sample request uses a bearer token to list invoices for a merchant:

curl -v -X GET https:/api.zakeke.com/v1/designs/000-2p5ysDc6d0mC6FQXL0BHXA \
     -H "Content-Type:application/json" \
     -H "Authorization: Bearer <Access-Token>"

Access tokens have a finite lifetime. The expires_in field in the get Access Token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time the response was generated.

To detect when an access token expires, write code to either:

  • Keep track of the expires_in value in the token response. The value is expressed in seconds.

  • Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.

Before you create another token, re-use the access token until it expires.

2. Get an Access Token​

The get access token endpoint is https://api.zakeke.com/token

To get an access token, you pass your OAuth credentials in a get access token call. To make this call, you can use either cURL on the command line or the Postman app.

In response, the Zakeke authorization server issues an access token.

Re-use the access token until it expires. When it expires, you can get a new token.

N.B. OAuth tokens will be CLIENT-SERVER to default, so they can only be used for CLIENT-SERVER requests. For SERVER to SERVER requests to the endpoint, you need a S2S token for authentication.

To begin using using Zakeke API, follow these steps:

  • First, create an account on the Zakeke website.

  • Get your Zakeke API keys by going to this page and click on API keys tab section.

  • Go to this page.

  • Select the API tab section, then enter your system URL, Products Sync V3, and base currency of your system.

3. cURL Example​

Tips:
  • If you use Windows, use a Bash shell to make cURL calls.
  • If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.
  • Download cURL for your environment.

From the command line, run this command:

curl -X POST https://api.zakeke.com/token \
     -H "Accept: application/json" \
     -u "your_client_id:your_secret_key" \
     -d "grant_type=client_credentials"

Where:

EndpointAtribute
https://api.zakeke.com/token The get access token endpoint.client_id Your client ID.
secret Your secret key.
grant_type The grant type. Set to client_credentials.
  • View the sample response.

3.1 Postman Example​

1) Download Postman for your environment, and open Postman.

2) On the Authorization tab, select "Basic Auth" and then enter these information:

VerbEndpointAtribute
POSThttps://api.zakeke.com/tokenUsername Your client ID,
Password Your secret key.

3) On the Body tab, select or enter this information:

"Content-Type:   x-www-form-urlencoded"
"key:            grant_type"
"value:	         client_credentials"

4) Click Send

5) View the sample response

3.2 Sample Response JSON​

{
    "Access-Token": "Access-Token",
    "token_type": "Bearer",
    "expires_in": 32398
}

Where:

Access-TokenYour access token
expires_inThe number of seconds after which the token expires. Request another token when the current one expires

4. Access Token for S2S Endpoint Requests​

For Server to Server (S2S) requests to the various endpoints the authentication OAuth token must be S2S.

The way to get an authentication OAuth token S2S is the same as normal request except that, in addition of OAuth credential, you must sent the parameter access_type set on S2S mode:

4.1 cURL Example​

Tips:
  • If you use Windows, use a Bash shell to make cURL calls.
  • If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.

From the command line, run this command:

curl -X POST https://api.zakeke.com/token \
     -H "Accept: application/json" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -u "your_client_id:your_secret_key" \
     -d "grant_type=client_credentials" \
     -d "access_type=S2S"

5. Customer code and Visitor code into Access Token​

Some endpoints (es. such as order checkout on Zakeke: https://api.version.com/v1/order) require an autentication token with, in addition to your OAuth credentials, the visitor ID and / or user ID logged.

One or both of these parameters have to be sent to the token request:

NameData typeDescription
visitorcodestringIdentifier of visitor who is browsing on your store
customercodestringIdentifier of user who is logged on your store

5.1 cURL Example (Request for OAuth S2S token with User and Customer code)​

Tips:
  • If you use Windows, use a Bash shell to make cURL calls.
  • If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.

From the command line, run this command:

curl -X POST https://api.zakeke.com/token \
     -H "Accept: application/json" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -u "your_client_id:your_secret_key" \
     -d "grant_type=client_credentials" \
     -d "access_type=S2S" \
     -d "visitorcode=VISITOR_CODE" \
     -d "customercode=CUSTOMER_CODE"