Authentication

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

To fetch a token, you will first need to have a client configured.

Note

At this time, we have not automated setting up new clients. Please contact the ZEIL sales team for more information.

Once configured, you will be provided with a client_id and a client_secret for a sandbox environment that can be used to develop and test your integration.

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]

In most cases, each ATS client organisation will be issued their own set of credentials. If the ATS client organisation will be posting jobs on behalf of multiple other organisations, as a recruitment agency might do, you will also need to follow the directions in the Organisation Identification.

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

Organisation Identification {#org-header}

If you're accessing the API on behalf of multiple organisations, for example as an ATS aggregator, you'll need to also provide an organisation ID, which can be found in the organisation's setting on ZEIL.com. The organisation ID must be provided in a Z-Organisation-ID header.

Z-Organisation-ID: c627a329f22e