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.
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:
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.
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.
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:
GET <RedirectURL>/?client_id=<client_id>&code=<authorization code>
NOTE: This token cannot be used to make API calls, it is used only to securely retrieve the long-lived access token.
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:
<ClientID>:<ClientSecret>
Authorization: Basic <base64 encoded string>
For example
Given:
https://YOUR_DOMAIN/oauth_callback
6779ef20e75817b79602
31408421fb39334a730fc92e41e96986b60f6522a13f631ec93afa6f6c4e0cb3
l4b6iplj3r
Base64 Encode the ClientID and Secret:
$ 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
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:
{
"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.
The Access Token can now be used to make API calls by providing it in the Authorization
header.
For example:
curl -X GET "https://api.zentail.com/v1/salesOrder?status=PENDING" \
-H "AUTHORIZATION: v2podKNZ395VqsQ7dz0afA1T9HpfPQkvoJHHo3Vow4U=" \
-H "accept: application/json"
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.