Configuring Integrations via API

When you're only working with a few schools, it might be easiest to manually configure Edlink connections in your backend. As you scale, this will probably become impractical and you'll likely want to switch to an automated solution in order to save time and reduce error.

Here's what we recommend in order to keep your integrations in sync.

Use the Edlink Integration ID as a Primary Key

Edlink generates a unique ID for each district or university that your application is connected to. This is what we call the integration_id. You can find this ID in several places, including your Edlink Dashboard. This ID is stable and all data associated with a particular district can be tied back to this ID.

We recommend that you store the integration_id alongside the top-level organization (e.g., a district) in your system. This will allow you to differentiate between new district connections and old ones in a reliable manner (as opposed to relying on the institution's name or email domain).

Fetching a List of Connected Districts

Fetching a list of connected districts via the Edlink API is pretty straightforward. You can do so with the following request:

axios.get('https://ed.link/api/v1/integrations', {
    headers: {
        authorization: `Bearer YOUR_APPLICATION_SECRET_KEY`
    }
});

Please note, there is not currently a V2 equivalent of the API call as nothing really changed in this part of our data structure between V1 and V2. The application secret key is available on your Edlink Dashboard. You can learn more about how to generate this key in our guide on the subject. Please keep this key safe - if you believe it has been compromised, please alert us immediately so we can reset it.

This endpoint responds with a list of integrated districts. This list contains all of the metadata you should need (hopefully) in order to automatically configure the district in your database. Here's a sample response:

{
    "$data": [
        {
            "id": "3c58530b-53c5-4fff-b87b-14b6979bd3b2",
            "status": "active",
            "scope": "all",
            "created_date": "2022-09-15T17:02:29.278Z",
            "updated_date": "2022-09-15T17:02:29.278Z",
            "permissions": [ ... ],
            "access_token": "ZLQkLniHyIrw6AbcaNtlKMRyfSutuvIY",
            "source": {
                "id": "64d8f1fa-d68a-4096-84ad-a64104759aaf",
                "status": "active",
                "name": "Schoology",
                "created_date": "2020-02-09T00:52:54.970Z",
                "updated_date": "2020-02-09T00:52:54.970Z",
                "sync_interval": 86400
            },
            "provider": {
                "id": "47eda4bf-7440-4cd8-9ee7-44cafb98486b",
                "name": "Schoology",
                "icon_url": "/source/schoology.png",
                "application": "schoology",
                "allows_data_sync": true
            },
            "team": { ... },
            "entity": { ... }
        }
    ]
}

You can find a full explanation of this endpoint here. Please bear in mind, this information is very sensitive (in particular, the access token) and should be handled with care. Do not save this response to an unsecured server or logging service. Do not share these details with anyone else.

Building a Cron Job

We recommend that you create a cron job to run this process every hour or so. You'll want to first retrieve a list of all the available integrations, then compare it to the list of integrations that already exist in your database. If you see any Integration IDs that you do not recognize in the API response from Edlink, you should insert a new district row and store the information relevant to your product (probably the access token, district name, and provider details).