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, including in the Aeries Hosted environment, the cookie(s) that come with the authorization grant response need to be saved for all subsequent calls.
Cookie Example: ASP.NET_SessionId=jtawmu34vrjz11zuatakqrhv; path=/; HttpOnly,ARRAffinity=9dddcbdcecc4856635bbde71041bc38a2ce605cfb0b7e3ae4f9b921a3fffe9fa;


Method A: 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:



Method B: Authorization Code Flow


1. Request Authorization Code

Issue a POST request to obtain an authorization code.

URL: base URL + /v1/oauth/authorize

Parameter: client_id

POST https://demo.aeries.net/aeries/v1/oauth/authorize
Request Body: 
    client_id: "1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550"


Response:



The authorization code is valid for 5 minutes and is used in the next step to acquire an access token.


2. Acquire Access Token

Issue a POST request to acquire an access token.

URL: base URL + /v1/oauth/token

Parameters:

          client_id

          client_secret

          authorization_code

          scope: OneRoster

POST https://demo.aeries.net/aeries/v1/oauth/token
Request Body:
    client_id: "1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550"
    client_secret: "68019dbf8d8ba82980dd148eecc3977ac0d7f1f040d444225874c88eb80b9c1a"
    authorization_code: "047031056252411df31b799e2db97b633190ecaa003c1b8f4747ae8c7b439296"
    scope: "OneRoster"


Response:



The access token is valid for 12 hours, and the refresh token is valid for 7 days.


3. Refresh Access Token (if needed)

If the access token has expired, but the refresh token is still valid, the refresh token can be used to acquire a new access token. Each refresh token is valid for one use; when it is used, a new refresh token will be provided in the response. Issue a POST request to refresh the access token.

URL: base URL + /v1/oauth/token

Parameters:

          client_id

          client_secret

          refresh_token

          grant_type: refresh_token

POST https://demo.aeries.net/aeries/v1/oauth/token
Request Body:
    client_id: "1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550"
    client_secret: "68019dbf8d8ba82980dd148eecc3977ac0d7f1f040d444225874c88eb80b9c1a"
    refresh_token: "579c08a738686b6f4e1a6776a6a3c339"
    grant_type: "refresh_token"


Response:



Authenticate and Request a Resource

With a valid access token obtained using any of the above methods, 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: