Zunia OneRoster API
Introduction
Education Horizons has developed an API based on the OneRoster® 1.1 specification for Zunia. 1EdTech’s OneRoster standard solves a school’s need to securely and reliably exchange roster information, course materials and grades between systems. More information is available on the IMS Global website: https://www.1edtech.org/standards/oneroster.
By using the OneRoster standard Education Horizons can ensure interoperability with other vendors that have implemented or will implement the same standard such as Google Classroom and Microsoft Teams for education that Zunia has integrations for out of the box thanks to the Zunia OneRoster API.
The Zunia OneRoster API is also available to third-party developers as a described here to extend and enhance Zunia's capabilities giving schools the tools they need to succeed.
Authentication
Authentication
- OAuth 2.0: oAuth2OneRoster
Zunia OneRoster API implements OAuth2 as described in the OneRoster® 1.1 specification section 3.6.2. OAuth2 Bearer Token Authorization.
Generate an API Key
To authenticate with the Zunia OneRoster API an API key is required. Follow the steps here to generate an API key.
To access all the Zunia OneRoster API endpoints choose "Advanced" when creating the API key with the GET, PUT and DELETE HTTP verbs selected and assign a permissions group to the key containing the permissions from the table below.
| Permission name | Permission description |
|---|---|
| View classes | This permission set allows the user to view classes only. |
| View subjects | This permission set allows the user to view subjects only. |
| Student view | This permission set allows the user to view the student details along with search student profiles. |
| Future student view | This permission set allows the user to view the future student along with search future student profiles. |
| Past student view | This permission set allows the user to view the past student along with search past student profiles. |
| Staff view | This permission set allows the user to view the staff details along with search staff profiles. |
| Community view | This permission set allows the user to view community profiles. |
| View school configuration of enrolment year | This permission set allows the user to view the enrolment year configuration settings. |
| View Maintain school configuration of enrolment period | This permission set allows the user to view the enrolment period configuration settings. |
Request an Access Token
This step involves sending a request to the /token endpoint to obtain an access token using the client credential obtained in the previous step. Ensure that the Client ID and Secret are correctly encoded and the necessary scopes are provided.
Note: In the example below replace <CLIENT_ID> and <CLIENT_SECRET> with the API key credentials obtained in the previous step.
HOST=public-api-ap-se-2.zunia.com
CLIENT_ID=<CLIENT_ID>
CLIENT_SECRET=<CLIENT_SECRET>
BASIC_AUTH_CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)
curl --location "https://$HOST/api/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Authorization: Basic $BASIC_AUTH_CREDENTIALS" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=https://purl.imsglobal.org/spec/or/v1p1/scope/roster-core.readonly https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.readonly https://purl.imsglobal.org/spec/or/v1p1/scope/resource.readonly https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.readonly https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.createput https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.delete"
Use the Access Token to make requests
After receiving the access token from the authorization server use it to make requests to the Zunia OneRoster API. Ensure the token is correctly placed in the Authorization header as a Bearer token.
Note: Replace <ACCESS_TOKEN> with the access token obtained in the previous step.
HOST=public-api-ap-se-2.zunia.com
ACCESS_TOKEN=<ACCESS_TOKEN>
curl --location "https://$HOST/ims/oneroster/v1p1/students" \
--header "Accept: application/json" \
--header "Authorization: Bearer $ACCESS_TOKEN"
| Security Scheme Type: | oauth2 |
|---|---|
| OAuth Flow (clientCredentials): | Token URL: https://public-api-ap-se-2.zunia.com/api/token Scopes:
|