This article is intended for Aeries administrators. There is a separate document intended for vendors that details every API End Point in the system, the parameters, and the output.
Aeries SIS contains an integrated API system. An "API" is an Application Programming Interface. It allows outside systems (like 3rd Party Vendors) to call functions inside of Aeries to perform actions like getting data out or changing information.
Aeries administrators can access the API Security page in the Security node of the navigation menu. This page allows the customer to create 3rd party product records and manage the permissions that each product is granted.
3rd Party Product ↑
On the API Security page, the Aeries administrator can Add, Change and Delete records for 3rd party products. When adding a new product, the Product Name is required. A Comment can be added to store additional information if needed. Vendors that are accessing the Aeries Public API should not have a value in the Type dropdown.
If the vendor will access the Aeries OneRoster API, select OneRoster in the Type dropdown.
If the vendor will access the upcoming Aeries Student App, select the Student App in the Type dropdown. Two additional Google Client ID options are available for vendors accessing the Aeries Student App API.
Click the Insert button to save the record.
Exclude Expired Accounts for Staff Data - Enabling this option will exclude expired User records from the Staff endpoint result. This will be honored using the Expiration Date field (UGN.XD) on the Security Users page.
Information to Provide to the Vendor ↑
Aeries Public API
Once saved, the records set up to access the Aeries Public API will have an option to Display Certificate Details.
You will need to provide the 3rd party vendor with the following pieces of information:
Aeries URL: This is the base URL for your Aeries Web application. The website needs to be publicly accessible from outside your local network, and it is HIGHLY recommended that it be secured with an SSL certificate (HTTPS). Simply browse to your Aeries login page, then copy everything before the last slash (“/”) in the browser’s address bar. In the example below, the Aeries URL is https://aeries.mydistrict.org.
Note: If your Admin and Teacher Portals are not available externally or if they use Integrated Windows Authentication, then it is best to provide the URL of your Student Portal instead. The API works the same regardless of the portal type.
API Certificate: Using this unique string provides security for the Aeries API against unauthorized access. A sample Certificate is highlighted below for illustrative purposes only. Each Certificate will be different.
Note: Vendors may use different names for the API Certificate, but they are all referring to the same thing. Examples include “API Key”, “App Key”, etc. Although some vendors may refer to this information as “provided by Aeries”, there is no need to contact Aeries Support to obtain API-related information to give a vendor; all of the required information is available on the API Security page in Aeries.
Aeries OneRoster API ↑
The records set up to access the Aeries OneRoster API have an option to Display Consumer ID & Secret Keys for OneRoster.
You will need to provide the OneRoster vendor with the following pieces of information:
Consumer ID: The vendor will require this information for OAuth 2.0 authentication, as described in the OneRoster API Authentication article. A sample Consumer ID is highlighted below for illustrative purposes only. Each Consumer ID will be different.
Consumer Secret Key: The vendor will require this information for OAuth 2.0 authentication, as described in the OneRoster API Authentication article. A sample Consumer Secret Key is highlighted below for illustrative purposes only. Each Consumer Secret Key will be different.
Aeries Student App API ↑
The records set up to access the Aeries Student App API have an option to Display Consumer ID & Secret Keys for Vendor.
The Aeries Student App API is not fully developed at this time. Once it is fully functional you will need to provide the Student App API vendor with the following information: Vendor ID, Secret Data, Private Key.
IMPORTANT: Do not share a Certificate, Consumer ID, or Consumer Secret Key with anyone other than the vendor for which it was created. Always create a separate 3rd party product record for each vendor/product that will access the API. These credentials cannot be changed once they are created. If credentials are compromised, the 3rd party product record must be deleted and a new one created.
After creating a 3rd party product record, the Aeries administrator can grant appropriate permissions to various tables and program areas within Aeries. The 3rd party vendor should be prepared to provide information on which permissions are required for their product to access the API. If it is unclear what permissions are needed, we recommend using your best judgment to determine the minimum permissions required for the 3rd party product to interface with Aeries based on the functionality of that particular product. The image below illustrates some of the current tables and program areas that are available. As the API is enhanced, there will be more areas from which to choose.
The OneRoster and Student App APIs will display limited permissions based on the each particular API.For the permissions required for the OneRoster API, refer to the OneRoster API setup article.
There are two types of API permissions: Read and Update. Read permissions only allow Aeries data to be retrieved via the API but not modified. Update permissions allow Aeries data to be modified via the API. Not all areas of the API currently support Update permissions, but more will be added as the API continues to be enhanced.
To grant a permission, click the box next to the appropriate table/program area under the Read or Update column, and the box will become checked with a green background. To remove a permission, click the box again, and the check mark and green background will go away. There is no “Save” button for API permissions. Changes are saved immediately as you click the various boxes.
Default Database and Multi-Year Access ↑
The Aeries API utilizes the AeriesNetConnections.config file to determine the database to which it should connect. The API can only be used to connect to the Default Database Group defined in this file. The API can be used to connect to a previous year database within the default Database Group if a parameter named DatabaseYear is included in the query string of the API request. If the DatabaseYear parameter is omitted or invalid, then the API will connect to the Default Year within the default Database Group. The DatabaseYear parameter should be in the format of “YYYY”, using the year at the start of the school year (e.g., “2017” for the 2017-2018 school year).
Aeries Software Elite Partners ↑
Our Elite Partners are companies that have formal business relationships with Aeries Software that can involve co-marketing and sales campaigns as well as financial relationships. Our Elite Partners automatically have 3rd party product records on the API Security page. The Elite Partner status is indicated by a red message above the product name.
These records cannot be deleted. Some Elite Partners may have Certificates that are not visible to the customer, while others may be visible. If the Certificate is not visible, then it is only necessary to grant the permissions in order for that Elite Partner to access the API. If the Certificate is visible, then it must be provided to the Elite Partner. The situation may vary depending on the Elite Partner.
Note: If no permissions are granted, then the Elite Partner will not be able to access your Aeries data via the API. Aeries Software and our Elite Partners respect the security and privacy of our customers’ data.