Aidi API operating documentation (AESA)

Why different accesses than the web platform?

Since the Aidi External System API (AESA) offers administrator-level access to the Aidi platform, we want to provide easily manageable access, allocated for a fixed period, for development and integration purposes. The implemented authentication process described below is based on the OAuth 2.0 industry standard.

Glossary

AESA Access Credentials: Set of ID and secret code used to access the AESA documentation (Swagger) and generate a session token required to execute API calls. The ID is 12 characters long and the secret code is 32 characters long.

Session Token (X-Aidi-Token): Accreditation used to make requests with the API, up to 8096 characters long. 

Creation of AESA Access ID

Use of AESA access credentials to create session tokens via Swagger

Details of AESA functionalities

Access AESA Credentials

Delete AESA Credentials

Creation of AESA Access ID

New credentials should be created for each individual instance used to access system settings. For example, developers requiring access to pre-production environments should be assigned individual credentials. Each automated service in production should also be assigned individual credentials. There is no limit to the number of credentials that can be used simultaneously.

The user who creates the credentials must have an Administrator access profile.

1. In the left-hand menu of the Aidi web platform, click on System settings.
2. In the AESA Configuration tab, enter the desired expiry date for the new credentials.

• • If you do not enter a date and time, the default expiry time for the generated key is 30 minutes.
  • If you select the expiry date and time, this must be done according to your current time zone.

3. Press the New credential button.
4. Wait a few seconds and a new line will be added at the end of the list.

Both ID and Secret codes will be required later for authentication. We recommend that you keep them in a safe place, such as in a password manager. 

⚠️Warning: The secret code is only visible immediately after it has been generated and only to the user who generated the credential. It will be hidden afterwards and cannot be recovered. Another credential must be created.

Use of AESA access credentials to create session tokens via Swagger

Multiple session tokens can be created and used simultaneously for the single set of credentials (ID and secret code). Session tokens are only valid for 30 minutes from the time of generation.

Steps

1. Connect to the Swagger AESA interface (https://client_domain_name.aidi.io/v1/apidocs) using the ID and secret code generated previously as username and password respectively.

2. Open the POST /v1/oauth2.0 section by clicking on the header.
3. Click on the Try it out button. 

4. In the body section, replace ‘string’ in the string ‘’client_id‘: “string”’ with the previously generated ID and replace ‘string’ in the string ‘’client_id‘: “secret”’ with the previously generated secret code. 
5. Click on the Execute button.

6. A response with status code 200 should be displayed below with the following response:

{

"token_type" : "Bearer",

"access_token" : "<session_token>",

"expires_in" : 1800

}

7. Copy the session token (<session_token> in the example above) from the response (without the double quotes). 

✏️Note: This token is valid for 30 minutes.

8. Select the API endpoint you want to use (for example, GET /v1/authed).
9. Click on the Try it out button.

10. Paste the Session Token into the input field of the X-Aidi-Token header.
11. Click on the Execute button.

12. A Responses section will appear and will be subdivided into 3 sections: 

• The Curl (Client for URL), which provides all the input information for the request, including the headers.
• The Request URL, which provides the request URL.
• The Server Response, consisting of the Code and Response body of the request. 

Details of AESA functionalities

Parameters

Several of our GET endpoints offer the option of filtering the data collected in order to obtain entries meeting certain criteria. The parameter information will always be defined from the URL. To find out the syntax used by these parameters, we suggest you test the request using the Swagger interface. For example, the parameters nomenclature used to filter projects by Id is as follows:

It is also possible to apply several filters at once. 

Here's what the query URL looks like if you add, for example, the filter by administrative unit identifier:

The combination of filters only supports AND logic, and all the entries in a filter (for example: id=3, ...) support OR logic (either id=3 or id=...). Therefore, in the example above, the project returned must have one of the ids defined in the filter and must have one of the administrative unit ids defined in the filter.

Structure required for POST, PUT and PATCH

To find out the structure required for POST, PUT and PATCH endpoints, simply navigate to the body section and click on Model. Entries marked with a red asterisk are required for the call to succeed. Here's an example:

Access AESA Credentials

The user who accesses the credentials must have an Administrator access profile.

In the left-hand menu of the Aidi web platform, click on System settings.

You will see the list of credentials already created in the AESA Configuration tab.

1. ID: Main indicator of a set of credentials.
2. Secret: This code is only visible to the user who generated it and is only displayed for a few moments after it has been generated. It is then hidden.
3. Creation date: Indicates the time at which the credentials were generated by the server. 
4. Expiry date: Server timestamp indicating when the credentials will expire. Note that expired credentials are not automatically removed from the list.
5. Last session: Indicates the time at which the credentials were last used to generate a session.

Delete AESA Credentials

Deleting credentials makes them unusable for creating new sessions and removes them from the API's list of credentials. This function should be used to ensure rotation of credentials as required.

The user accessing the credentials must have an Administrator access profile.

In the left-hand menu of the Aidi web platform, click on System Settings and you will see the list of credentials already created in the AESA Configuration tab.

1. Go to the menu with the 3 dots to the right of the line you want to delete.
2. Click on Delete.

The line will disappear from the list of credentials. Deleted credentials are kept in the Aidi archive for internal logging purposes. If you need information about old credentials (for auditing purposes, for example), please contact Aidi support.

Deleted credentials can no longer be used to generate a valid AESA session token.