Request Authorization

Securely accessing the Edlink API can be done through a variety of methods. This document will walk you through those methods and provide links to other useful guides along the way.

There are four main types of request authorization that you will need in order to interact with the Edlink API. These are: Graph API Requests, User API Requests, Meta API Requests, and Meta API Requests. Each of these request types requires a different type of access token to authenticate the request. Even though that may seem confusing at first, things should be clear once you understand the purpose of each type of request.

All requests must be made over HTTPS to ensure data is encrypted and secure. We will automatically redirect all requests not made via HTTPS.

Graph API Requests

The Edlink Graph API is a set of endpoints that allows you to make calls to a system on behalf of a district or university. This is the most broad-based access that you can receive from Edlink. Graph API requests are performed with an integration access token. Integration access tokens are unique for each district or university integration. Data returned from Graph API calls will be "scoped" to a specific district or university.

There is not currently a way to retrieve data for multiple different district integrations in a single request. This is intentional. Data for different institutions may reside (for legal reasons) in different geographic regions. We also encourage developers to sync data for different integrations in parallel for performance reasons at scale.

You can find the access token for an integration in two ways:

1. You can access the token manually by clicking on an integration in the Edlink Dashboard and copying it from the "Summary" page.
2. You can programmatically retrieve the token by making a request to the List Integrations Endpoint with an application secret.

To authorize a Graph API request, you will need to include the integration access token in the Authorization header of your request. The token should be prefixed with Bearer followed by a space and then the token itself. These integration access tokens do not currently expire.

Single Sign On Requests

There are a handful of endpoints in the Edlink API that deal specifically with Single Sign On (SSO) requests. These requests involve exchanging an Edlink authorization code for an access token and refresh token as a part of the OAuth 2.0 or OIDC authentication flows.

These requests are authenticated a little bit differently from the others on this page, however, it will be very familiar to you if you've worked with OAuth 2.0 or OIDC in the past. Instead of using some sort of token in the Authorization header, you will need to use the Application ID and Secret Key that you received when you created an application with Edlink. You can read more about how to authenticate these requests in their respective guides.

Once you have exchanged an authorization code for an access token, that access token can be used to make requests to the User API below.

User API Requests

The Edlink User API is a set of endpoints that allows you to make calls to a system on behalf of a specific person. This is notably different than the "broad based" access that you receive from the Graph API. User API requests are performed with a user access token. User access tokens are tied to a specific user and integration. Data returned from User API calls will be "scoped" to a specific user.

We generally suggest using the User API when interacting with assignments, submissions, and grades, because the LMS or SIS may implement important permissions checks to ensure that the user has the necessary permissions to access the requested data.

To authorize a User API request, you will need to include the user access token (from the SSO section above) in the Authorization header of your request. The token should be prefixed with Bearer followed by a space and then the token itself. These access tokens expire in 60 minutes, but they can be refreshed using the provided refresh token. Refresh tokens do not currently expire.

Meta API Requests

The Edlink Meta API allows you to programmatically interact with the Edlink Dashboard. Meta requests are not typically related to school data like the User or Graph APIs. Instead, they are used to manage your applications, integrations, sharing rules, and other settings in the Edlink Dashboard (i.e. "metadata").

Meta API requests are authorized with a Service Account access token. You can create service accounts and generate access tokens on the team settings page in the Edlink Dashboard. Service accounts should always be treated with the same level of security as your own account as they can be assigned broad permissions to manage your Edlink account.

To authorize a Meta API request, you will need to include the service account access token in the Authorization header of your request. The token should be prefixed with Bearer followed by a space and then the token itself. These tokens do not currently expire, but they can be manually rotated via the Edlink Dashboard.