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:
- Advanced 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:
- Name of the API Key
- Description of the API key
- First characters of the API Key (Access Key)
- Creation date
- Date of last use
- Status of the API Key: Active/Inactive
Create an API Key
Click on « See profile »
Open the « API KEYS » tab
Click on the button « Create a new API Key »
Enter a name and a description
Click on the button « Create a new API key »
Copy the API Key by clicking on the Copy button and save it in a safe place
Confirm the action by checking the check box
NotePlease note that for security reasons, the full API key(accesskey_secretkey) will only be displayed once during the process described above. A user can generate an API Key for each project/use of AT Internet REST API. To easily identify the API Key on the interface, we recommend that you give clear and accurate name and description to each API key.
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
NoteThis 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.
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.
Edit an API Key
From the table displaying all the API Keys, the user can edit each of them to:
- Update the name or description
- Make the API Key Inactive
As soon as an API Key is inactive, it can be deleted by the user.
NotePlease note that deleting an API Key is a definitive action. A deleted API Key cannot be recovered.
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
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.
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
- 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 :
- “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.
- Two users belong to this organization.
- The email of the first user is email@example.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 firstname.lastname@example.org
- 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.