Authentication

The ZEIL ATS API is protected by OAuth 2.0 Client Credentials authentication provided by AWS Cognito.

To get started with developing your integration, go to our sandbox environment and create an account and company page. Then follow the steps here to obtain a client_id and client_secret pair to develop and test your integration.

Credentials are issued per customer (not per user) and should be configurable in a central location within your ATS software as a one-time setup activity. The client ID and secret are all that should be needed to obtain tokens for communicating with the ZEIL ATS API.

As per the AWS Cognito documentation, you will need to make a POST request to the token issue endpoint with URL-Encoded Form content. You can either place the token request info in headers or in the body.

With either of these approaches, a JWT bearer token will be issued to you upon successful authentication, allowing you to access the ZEIL ATS API. This token will need to be placed on every request in an Authorization header.

Authorization: Bearer [your token]

Tip

The examples below use the sandbox authentication URL, which will be important for when the integration is being developed. The production authentication URL is https://auth.zeil.com/oauth2/token.

Credentials in Headers

When placing your credentials in the header, you will first need to base-64-encode a string with your client_id and client_secret separated by a colon :.

For example,

Gather your data
- client_id: 7hjs82961p
- client_secret: t03efk1796mim6d88ab8
Produce a formatted string
- 7hjs82961p:t03efk1796mim6d88ab8
Base-64 encode the formatted string
- N2hqczgyOTYxcDp0MDNlZmsxNzk2bWltNmQ4OGFiOA==
Prefix with "Basic"
- Basic N2hqczgyOTYxcDp0MDNlZmsxNzk2bWltNmQ4OGFiOA==

This will become the content of an Authorization header

Finally, in the body you'll need the following parameters:

grant_type=client_credentials
client_id=[your client_id value]

POST https://sandbox-auth.zeil.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic N2hqczgyOTYxcDp0MDNlZmsxNzk2bWltNmQ4OGFiOA==

grant_type=client_credentials&client_id=7hjs82961p

Credentials in Body

When placing your credentials in the body, you will need to add a special header for AWS:

X-Amz-Target: AWSCognitoIdentityProviderService.Client credentials request

Your client_id and client_secret then become additional parameters in the body. No Authorization header is required.

POST https://sandbox-auth.zeil.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
X-Amz-Target: AWSCognitoIdentityProviderService.Client credentials request

grant_type=client_credentials&client_id=7hjs82961p&client_secret=t03efk1796mim6d88ab8