Getting started with the 6clicks Developer API

This article provides developers with a step-by-step guide to effectively utilize the 6clicks Developer API.

Table of Contents:

• Getting access to the Developer API
• Using the Developer API
  • Authentication mechanism
  • Creating an API user account
  • Creating an API key
  • Managing API keys
  • Exchanging an API key for a JWT
  • Using the JWT in subsequent requests
  • Testing integration via Swagger (optional)

• Accessing the full API documentation

Getting access to the Developer API

You will need to contact 6clicks Support to enable API access for your instance.

Using the Developer API

Authentication mechanism

The 6clicks Developer API authenticates using an API key representing an active user in the system, wrapped in JSON Web Tokens (JWTs) for enhanced security. JWTs encapsulate user information and access privileges, offering advantages over simple API keys by incorporating expiry times and supplementary user data. 

Creating an API user account

You should create a dedicated API user account, with the necessary permissions for your integration requirements. This user will need a valid email address to receive the invitation.

1. Create a new user via the Administration > Users
2. Set the appropriate role or permissions for the API user account
   
   NOTE: The Integrations permission is required in order to access the Developer API and to create API keys in the next step
   

Creating an API key

1. Log into 6clicks with the API user account
2. In the main menu, navigate to Administration > Integrations
3. From the list, select 6clicks Developer API and click Connect
4. Click the Create API key button 
5. Give the API key a name. We recommend creating a key for each specific integration you plan to use
   
6. Optionally, you can upload and specify a certificate in PEM/PFX format to allow for mutual authentication
7. Click Create to save, and take note of the key. This is the only time you will be able to copy and save this key
   

Managing API keys

• API keys are create and delete only, they cannot be edited
• IMPORTANT: API keys are proxies of, and carry the same permissions as the user under which they were created:
  
  
  
  

Exchanging an API key for a JWT

Send a POST request to the Auth Controller "token" endpoint, with the API key in the 6Clicks-Api-Key header.

NOTE: You will need to replace app- with api- prefix in the request URL.

Example: 

POST https://api-au.6clicks.io/auth-api/1.0/auth/token 
Headers: 
6Clicks-Api-Key: <Your_API_Key> 

Upon successful validation of the API key, the API will return a JWT signed by the API provider. This JWT contains details regarding the user's access rights and includes an expiry time – default is 24 hours.

Example: 

"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI4NTcxIiwibmFtZSI6ImdyZWcucnVkYWtvdkA2Y2xpY2tzLmNvbSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2VtYWlsYWRkcmVzcyI6ImdyZWcucnVkYWtvdkA2Y2xpY2tzLmNvbSIsIkFzcE5ldC5JZGVudGl0eS5TZWN1cml0eVN0YW1wIjoiUUtWTVAzWlc1RklFT0pOWk5FRjQ2SlY1QklSQ0xDWVAiLCJodHRwOi8vd3d3LmFzcG5ldGJvaWxlcnBsYXRlLmNvbS9pZGVudGl0eS9jbGFpbXMvdGVuYW50SWQiOiIxNDE4IiwianRpIjoiZDcxZWNlOGYtMDFhMC00NDg0LWJlZjktZDI5NmZmZTE4MTg5IiwiaWF0IjoxNzEyMTExNDEzLCJ0b2tlbl92YWxpZGl0eV9rZXkiOiIxYmQ0NzhmOC02ZjdmLTRmYmItYTg3Ny01MjliNTQ0OTYwMmUiLCJ1c2VyX2lkZW50aWZpZXIiOiI4NTcxIiwibmJmIjoxNzEyMTExNDEzLCJleHAiOjE3MTIxOTc4MTMsImlzcyI6IjZjbGlja3MiLCJhdWQiOiJMZWdhbFJlZ1RlY2gifQ.SfaXT7Xpr_mqr15cH7GJ5uwZPieYxHHFcSlVwImd-Ww" 

Using the JWT in subsequent requests

Include the JWT value within the authorization header of any subsequent API requests using the Bearer method. 

Example:

GET https://api-au.6clicks.io/assessments-api/1.0/assessments 
Authorization: Bearer <Your_JWT_Token_Value> 
Headers: 
Content-Type: application/json 
Body: 
{ 
  "sorting": "Name", 
  "maxResultCount": 10, 
  "skipCount": 0 
} 

Testing integration via Swagger (optional)

If using Swagger for API testing, you can also include the JWT token for authorization.

1. Click on the Authorize button within Swagger
2. Paste the JWT token in the value window
3. This allows Swagger to include the JWT token in subsequent API requests for testing and documentation purposes

Accessing the full API documentation

The full API reference can be found under the Administration > Integrations > Developer API > API Documentation menu.

Here you will find a complete reference for all API endpoints in Swagger format.

By following these steps, developers can successfully authenticate and interact with the 6clicks Developer API, ensuring secure and authorized access to its features and data.