Zentail Authentication Flow

This document outlines the process for authorized partners with registered applications to get an access token for a Zentail customers account.

If you are looking to generate ad-hoc tokens for internal integration development, see this guide.

Pre-requisite: Application Registration

In order to utilize this authentication flow, you must first have received a Client ID and Client Secret from registering an application with Zentail.

During registration you will work with the Zentail team to identify the proper scopes required by your application. You will need to provide:

1. an Application Name
2. a Contact Email
3. a Redirect URI for sending authentication process communication
4. a Square Logo at least 50px x 50px that can be used in the Zentail UI

Once the app is registered you will receive a Client ID and Client Secret which are used to obtain an access token, via an OAuth2.0 Authorization Code Grant Flow, that is capable of make calls against a specific Zentail customers account.

Process Overview

An Access Token must be acquired for each individual Zentail customer account you wish to integrate with. The token will uniquely identify your application and the customers account.

All calls made with an Access Token will be scoped exclusively to that customers account.

OAuth Flow

The process for acquiring an Access Token follows the OAuth2.0 Authorization Code Grant Flow and will be initialized by a Zentail specialist or customer clicking an "Install" button in the Zentail platform.

Once that button is clicked the process will begin:

1. the Zentail system will verify that your application is active and registered.
2. Zentail will generate a one-time use Authorization Code and redirect the user currently installing the application to the Redirect URL provided during registration. The request will be of the format:

shell
GET <RedirectURL>/?client_id=<client_id>&code=<authorization code>

1. The application should then have the user log in to their system (or use their session if they are already logged in).
2. On the backend, the application should send a POST request to https://api.zentail.com/v1/token with a application/x-www-form-urlencoded request of the following format: grant_type=authorization_code&code=<authorization code>&redirect_uri=<redirect uri>.

The redirect URI must match the one provided during registration.

This request needs to be authenticated with basic auth:

• base64 encode the string of <ClientID>:<ClientSecret>
• Provide this string in the header: Authorization: Basic <base64 encoded string>

For example

Given:

• Redirect URI: https://YOUR_DOMAIN/oauth_callback
• Client ID: 6779ef20e75817b79602
• Client Secret: 31408421fb39334a730fc92e41e96986b60f6522a13f631ec93afa6f6c4e0cb3
• Authorization Code: l4b6iplj3r

Base64 Encode the ClientID and Secret:

shell-script
$ echo 6779ef20e75817b79602:31408421fb39334a730fc92e41e96986b60f6522a13f631ec93afa6f6c4e0cb3 | base64 -w0
Njc3OWVmMjBlNzU4MTdiNzk2MDI6MzE0MDg0MjFmYjM5MzM0YTczMGZjOTJlNDFlOTY5ODZiNjBmNjUyMmExM2Y2MzFlYzkzYWZhNmY2YzRlMGNiMwo=

Authorization: Basic Njc3OWVmMjBlNzU4MTdiNzk2MDI6MzE0MDg0MjFmYjM5MzM0YTczMGZjOTJlNDFlOTY5ODZiNjBmNjUyMmExM2Y2MzFlYzkzYWZhNmY2YzRlMGNiMwo=

As per this RFC where the Client ID is the user, and the Client Secret is the pass.

Then send the POST Request

shell
curl -X POST "https://api.zentail.com/v1/token" \
  -H "AUTHORIZATION: Basic Njc3OWVmMjBlNzU4MTdiNzk2MDI6MzE0MDg0MjFmYjM5MzM0YTczMGZjOTJlNDFlOTY5ODZiNjBmNjUyMmExM2Y2MzFlYzkzYWZhNmY2YzRlMGNiMwo=" \
  -d grant_type=authorization_code \
  -d authorization_code=l4b6iplj3r \
  -d redirect_uri=https%3A%2F%2YOUR_DOMAIN%2Eoauth_callback

If the application is successfully authorized the response to that POST request will be a 200 status code with the following JSON body:

json
{
  "access_token": "v2podKNZ395VqsQ7dz0afA1T9HpfPQkvoJHHo3Vow4U=",
  "token_type": "bearer"
}

The access token returned there should be associated with the currently authenticated user's account. It should be used to make all subsequent requests on behalf of that user and will apply only to the Zentail customer account that started the process.

Using the Token

The Access Token can now be used to make API calls by providing it in the Authorization header.

For example:

shell
curl -X GET "https://api.zentail.com/v1/salesOrder?status=PENDING" \
  -H "AUTHORIZATION: v2podKNZ395VqsQ7dz0afA1T9HpfPQkvoJHHo3Vow4U=" \
  -H "accept: application/json"

Updating the Application registration

Currently, there is no Zentail UI for managing the Application. Change requests can be submitted to product@zentail.com.

Please include the application name and ClientID in the request.