API Keys

Definition

An API Key is a string of characters that can be generated by a user after the authentication on Piano Analytics. An API Key aims at being used when querying AT Internet REST API instead of providing login details using basic authentication.

Rely on an API Key

An API Key gives the same permissions as the user who created it. If the user loses rights on a site, then he won’t be able to use his API key to get data on this site anymore. If the user gets rights on a new site, then he will be able to use his API key to get data on this site.

The API Key aims at being used with REST URLs retrieved from

. We invite you to use an API Key instead of providing login details using basic authentication, when querying the API with an external tool (Script or other).
If you are an SSO user, you must use an API Key to query AT Internet REST API.

Rights to create an API Key

An API Key can only be created by an authenticated user who can manipulate data. This user must have at least one of the following roles:

• Administrator
• Delegates
• Advanced Analyst
• Analyst
• or Custom Role with the “Handle data” tool
• Data Supervisor

The API Key is created, enabled, disabled and deleted by each user independently.

Display your existing API Keys

The API Keys are displayed under your Profile page > API Keys tab, in a table providing the user with the following information:

1. Name of the API Key
2. Description of the API key
3. First characters of the API Key (Access Key)
4. Creation date 
5. Date of last use 
6. Status of the API Key: Active/Inactive

Create an API Key

1. Click on « See profile »
   

2. Open the « API KEYS » tab

3. Click on the button « Create a new API Key »
   
   
   

4. Enter a name and a description

5. Validate with the button « Create a new API key »

6. Copy the API Key by clicking on the Copy button and save it in a safe place

7. Confirm the action by checking the check box

Use an API Key

Depending on the environment requesting the API, you can use various parameters:

From an external environment like Postman:

Postman is a program that can help you trigger API calls outside your browser, specifying request headers and handle authentication.
In Postman or any other solution you use to call APIs you can rely on these 2 methods.

• Request header
  After adding your API call URL in the GET field, get in the Headers tab and add a new request header named x-api-key with the value matching this format accesskey_secretkey.
  
  
• Basic authorization
  You can get in the Authorization tab to pick Basic Auth and fill UserName field with your Access Key and Password with your Secret Key.
  
  

From a browser:

• Standard direct URL
  

  Note

  This method is the least secured, because your credentials could potentially be listened/stolen by malicious software. If you can rely on any other method please do the switch.
  Pick your configured API call URL from Data Query and trigger the call in a new tab.
  You will then see a login form from your browser requesting an Access Key and a Secret Key.
  Fill these fields in, press enter and get your results.
  
  
• Prefixed URL
  Pick your configured API call URL from Data Query and add your Access Key and Secret Key like this accesskey:secretkey@ as a prefix to your call. This will add the Access Key and Secret Key as a request header when you trigger the call and get your results.

  https://3d0860524341:ee5076836541d5g75he2f49e5d133dacc8762ccb@api.atinternet.io/data/v2/json/getData?&columns={d_source_global,m_visits}&sort={-m_visits}&space={s:123456}&period={R:{D:'-1'}}&max-results=50&page-num=1

Edit an API Key

From the table displaying all the API Keys, the user can edit each of them to:

1. Update the name or description
2. Make the API Key Inactive

As soon as an API Key is inactive, it can be deleted by the user.

Secure your API Key

If you use API Keys, please make sure:

• To keep them in a safe place.
• If you have to share an API Key with someone, create a new one with a specific name and description and then disable or delete it as soon as you can.
• To delete the useless API Keys on a regular basis.
• To renew the API Keys used in your programs on a regular basis.

Check your organisation's API Keys usage

Quick view

Administrators and delegates can see in Access Rights' Users table, the last use of an API Key per account.
This field counts every attempt of a user to authenticate through one of his API Keys.
If the authentication is not allowed but the user is still listed in your users list (for example suspended accounts), this field will be updated by the attempt date even if it didn't validate the request.

Full view

The administrator(s) of the organization are the only users who can get the API-keys list.

The API KEYs list can be reached at the following endpoint. This call is made by HTTP request using the
GET method: https://api.atinternet.io/api/config/v1/right/manage/organization/current/users/details

This endpoint requires to use an API-key, you can create in your profile page under the API-key
section. This API-key can be used as a request header.

Request header example

• https://api.atinternet.io/api/config/v1/right/manage/organization/current/users/details 
• x-api-key: ac0481a1ae0f_8c1af********************

This call retrieves the API-keys of all the users of the organization. The results are grouped by user.
Here is a body response example :

[
{
 "apiKey": [
 {
 "isActive": true,
 "accessKey": "5d6479******",
 "creationDate": "2018-12-13T09:07:40.735Z",
 "lastUseDate": "2019-01-09T09:14:33.014Z"
 }
 ],
 "userId": 5146**,
 "email": email@atinternet.com
}
{
 "apiKey": [
 {
 "isActive": true,
 "accessKey": "5d6479******",
 "creationDate": "2018-12-13T09:07:40.735Z",
 }
 {
 "isActive": false,
 "accessKey": "4dtd479******",
 "creationDate": "2019-01-03T09:07:40.735Z",
 }
 ],
 "userId": 2236**,
 "email": email2@atinternet.com
}
] 

• “isActive” value can be “true” or “false”. It represents the status of the API-key.
• “accessKey” is a unique string of characters corresponding to the first characters of the API-key.
• “creationDate” represents the date the user created the API Key. Format is YYYY-MMDDTHH:MM.SS.
• “lastUseDate” represents the date the user used the API Key for the last time. Format is YYYYMM-DDTHH:MM:SS.
• “userId” is a unique string of characters representing the user.
• “email” is the email of the user.

Example analysis:

• Two users belong to this organization.
• The email of the first user is email@atinternet.com
  • This user has one API-key
  • This API-key is active
  • It has been created on December 13th 2018 at 9:07:40
  • It has been used on January 9th 2019 at 9:14:33 for the last time
• The email of the second user is email2@atinternet.com
  • This user has two API-keys
  • None of them have been ever used
  • The first one is active
  • The second one is not active

Deleted API-Keys are not taken into account in the response.