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 + /v2/oauth/token

Request Header:

          authorization: Basic <client_credentials>

POST https://demo.aeries.net/aeries/v2/oauth/token
Request Headers:
    authorization:"Basic MTI3OWU1YzZiNzQ3YjZkNjJiN2M3NmRiM2EyMDVkNDBlYjc0NThlNjc4YTkwNDkzZDUzN2Q1YWY2Yjk1MzU1MDo2ODAxOWRiZjhkOGJhODI5ODBkZDE0OGVlY2MzOTc3YWMwZDdmMWYwNDBkNDQ0MjI1ODc0Yzg4ZWI4MGI5YzFh"


Response:



Using the Request Headers approach, the client credentials are encoded to Base64 format. This is the preferred approach.


Alternatively, the client credentials can be passed in the body of the request, as demonstrated below.


URL: base URL + /v2/oauth/token

Parameters:

    client_id

    client_secret

    grant_type: client_credentials

POST https://demo.aeries.net/aeries/v2/oauth/token
Request Body:
    client_id: "1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550"
    client_secret: "68019dbf8d8ba82980dd148eecc3977ac0d7f1f040d444225874c88eb80b9c1a"
    grant_type: "client_credentials"


Response:



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

Request Header:

          authorization: Bearer <access_token>

Example:

GET https://demo.aeries.net/aeries/ims/oneroster/v1p1/orgs



Response: