This article explains the steps required to enable access to the Aeries OneRoster API.
The steps described in this article can only be completed by an Aeries Administrator.
Giving a vendor access to the Aeries OneRoster API is simple. To begin, create an entry for the vendor. Instructions can be found in the API Security article.
The OneRoster check box must be checked to enable the vendor to access the OneRoster API. After checking the box, click the Update button.
Next, check the box labeled Display Consumer ID & Secret Keys for OneRoster.
Make note of the Consumer ID and Consumer Secret Key that display. The core security of the OneRoster API is different from that of the regular Aeries API. For OneRoster, the vendor will NOT use the Aeries Certificate, but will use the Consumer ID and Secret Key instead.
You will need to provide the 3rd party vendor with three 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, it MUST be secured with a digital certificate (HTTPS), and the server MUST support TLS 1.2. If you are uncertain of the base URL, simply browse to your Aeries login page, then copy everything before the last slash (“/”) in the browser’s address bar.
- Consumer ID: The string of letters and numbers, exactly as displayed on the API Security page. The vendor may also refer to this as the “Client ID”.
- Consumer Secret Key: The string of letters and numbers, exactly as displayed on the API Security page. The vendor may also refer to this as the “Client Secret”.
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. In the example below, the Aeries URL is https://aeries.mydistrict.org.
IMPORTANT: Do not share a 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. The Consumer ID and Secret Key cannot be changed once they are created. If they are compromised, the 3rd party product record must be deleted and a new one created.
OneRoster API permissions are configured in the same way as permissions for the regular Aeries API. The following is a list of permissions that are needed for the complete set of OneRoster API endpoints that Aeries currently supports. More may be added in the future.
- Student Data
- Student Data
- Gradebook Scores
- Gradebook Category
- Gradebook Assignment
- Teacher Data
- Master Schedule
- Course Data
- School Information
After completing the steps in the above section on API Security, go to the School Options page (under School Info) while logged in at the District level. Click the Change button to enter Edit mode.
You will see a section named OAuth Settings. Check the box labeled Enable.
The following warning message will display. Click OK to continue.
The following options will display.
Signing Certificate: Click the magnifying glass to display a list of available certificates stored on your web server. Select the correct certificate that is used to secure your Aeries Web site.
IMPORTANT: As the warning message indicates, these settings will not take effect until the Aeries application is restarted in IIS. This can be accomplished by recycling the Application Pool under which Aeries is running or by resetting IIS. This will terminate all active user sessions, which may result in lost work and therefore is recommended to be done outside regular hours.
Note: Aeries Hosted customers should contact Aeries Support to have this step completed to ensure that the correct certificate is selected and that the recycling of the Application Pool can be coordinated.
There are additional options that apply to both the OneRoster API and the OneRoster CSV extract. Those options are detailed in the OneRoster CSV Extract article here.