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
1. Request Authorization Code
Issue a POST request to obtain an authorization code.
URL: base URL + /v1/oauth/authorize
Query string parameter: client_id
https://demo.aeries.net/aeries/v1/oauth/authorize?client_id=1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550
Response:
The authorization code is valid for 5 minutes and is used in the next step to acquire an access token.
Cookies: Due to the common implementation of server load balancing, including in the Aeries Hosted environment, the cookie(s) that come with this response need to be saved for all subsequent calls.
Cookie Example: ASP.NET_SessionId=jtawmu34vrjz11zuatakqrhv; path=/; HttpOnly,ARRAffinity=9dddcbdcecc4856635bbde71041bc38a2ce605cfb0b7e3ae4f9b921a3fffe9fa;
2. Acquire Access Token
Issue a POST request to acquire an access token.
URL: base URL + /v1/oauth/token
Query string parameters:
client_id
authorization_code
client_secret
scope: OneRoster
https://demo.aeries.net/aeries/v1/oauth/token?client_id=1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550&authorization_code=047031056252411df31b799e2db97b633190ecaa003c1b8f4747ae8c7b439296&client_secret=68019dbf8d8ba82980dd148eecc3977ac0d7f1f040d444225874c88eb80b9c1a&scope=OneRoster
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
Query string parameters:
client_id
client_secret
refresh_token
grant_type: refresh_token
https://demo.aeries.net/aeries/v1/oauth/token?client_id=1279e5c6b747b6d62b7c76db3a205d40eb7458e678a90493d537d5af6b953550&client_secret=68019dbf8d8ba82980dd148eecc3977ac0d7f1f040d444225874c88eb80b9c1a&refresh_token=579c08a738686b6f4e1a6776a6a3c339&grant_type=refresh_token
Response:
4. 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:
