This article explains the steps required to authenticate to the Aeries OneRoster API and issue a request to the API.
This information is intended for vendors attempting to access the OneRoster API or for Aeries Administrators wishing to test the OneRoster API.
Aeries utilizes OAuth 2.0 Bearer Token Authorization to grant access to the OneRoster API. This section details the steps required to obtain and utilize the access token. For the examples in this article, we will use the following information from the public Aeries Demo site:
Aeries Base URL: https://demo.aeries.net/aeries
Client ID: 1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550
Client Secret: 68019dbf8d8ba82980dd148eecc3977ac0d7f1f040d444225874c88eb80b9c1a
Cookies: Due to the common implementation of server load balancing, the cookie(s) that come with the access token response need to be saved for all subsequent calls.
Cookie Example: ASP.NET_SessionId=jtawmu34vrjz11zuatakqrhv; path=/; HttpOnly,ARRAffinity=9dddcbdcecc4856635bbde71041bc38a2ce605cfb0b7e3ae4f9b921a3fffe9fa;
Acquire Access Token: Client Credentials Flow
Issue a POST request to acquire an access token.
URL: base URL + /token
authorization: Basic <client_credentials>
POST https://demo.aeries.net/aeries/token Request Headers: authorization:"Basic MTI3OWU1YzZiNzQ3YjZkNjJiN2M3NmRiM2EyMDVkNDBlYjc0NThlNjc4YTkwNDkzZDUzN2Q1YWY2Yjk1MzU1MDo2ODAxOWRiZjhkOGJhODI5ODBkZDE0OGVlY2MzOTc3YWMwZDdmMWYwNDBkNDQ0MjI1ODc0Yzg4ZWI4MGI5YzFh"
Using the Request Headers approach, the client credentials are encoded to Base64 format. This is the preferred approach.
Authenticate and Request a Resource
With a valid access token, a resource may be requested from the OneRoster API provided that permission has been granted to the underlying security area by the Aeries Administrator. The URL is constructed as described in the Available Endpoints article.
Issue a request with the appropriate HTTP verb to access the endpoint.
URL: base URL + root URL + version + endpoint
authorization: Bearer <access_token>