Quick start guide

Onboarding with EduMS

Step 1. Introduction with EduMS.

Let’s get to know each other and get ready to work together. We will discuss what you can expect during the integration process. Afterwards, we will have a technical onboarding meeting to discuss the implementation details and expectations.

Step 2. Receive your credentials and get set up.

To move further, send an email to support@edums.nl, providing the following essential details:

• Name of the company.

• The goal of your integration.

• Your business e-mail address. Make sure this is an inbox you have access to, as it will be used for account and password verification.

• Contact person(s) and their contact details whom we should invite for the onboarding calls, both the general and the technical ones.

Example:

• Name of the company: Supercourses

• Goal: Want to collect, process and return orders

• Business e-mail address: info@supercourses.com 

• Contact person and email address: John Smith (account manager) jsmith@supercourses.com; John Doe (developer) jdoe@supercourses.com

Step 3. Integrate in Acceptance.

Throughout the integration process, our dedicated EduMS team will be by your side, ready to answer any questions you may have. We will also set up a convenient Slack channel for smooth communication and document sharing.

Step 4. You're good to go to Production. Voila!

Deploy to your production environment. Congratulations! You're now fully prepared to embark on your EduMS journey.

Subscription key

What it is

EduMS requires a subscription key to be included in the requests on the Production environment. This key identifies the entity (your company) that is performing the request. 

Subscription key is complemented by the bearer token [link] which allows to identify the specific user and their access rights. The subscription key does not replace the need for the client id and the secret, as you still need those to generate the bearer token.

If you do not include the subscription key or include an invalid one, then you won’t be able to access any data.

Primary and secondary subscription keys

You will receive two subscription keys, the primary and the secondary one. 

Oftentimes, developers use the primary key for the system-to-system communications, and the secondary one for debugging purposes (e.g. it is easier to spot a request coming in when it has a different key).

EduMS does not enforce rules on the usage for the two keys, you can use them in the way that suits your goals best.

Non-production keys

EduMS provides separate subscription keys for the non-production (ACC) and production (PRD) environment, per client. You will need to implement them separately per environment. 

In the Acceptance environment EduMS does not validate the key, but you are still encouraged to send it. You will receive the Production keys after the integration in ACC is signed off by EduMS.

Retry patterns

In case the first key fails, you can send the second one without a delay. It is unlikely that both will fail, but if this is the case, retry the entire call starting with the first subscription key. 

EduMS recommends implementing sliding retries with a maximum of 5 retries with an exponential delay.

Updating the security keys for security purposes

It is recommended that you periodically regenerate and update the keys, for security purposes. The primary and secondary key slots can be used to rotate keys gradually. If your application generally uses the primary key, you can copy the primary key into the secondary key slot, and only then regenerate the primary key. The new primary key value can then be configured into the client applications, which have continued access using the old primary key in the secondary slot. Once all clients are updated, you can regenerate the secondary key to finally retire the old primary key.

How to get your subscription keys

1. Log in on https://acc-developers.edums.nl or  https://developers.edums.nl

2. Go to the menu item ‘Profile’

3. In section ‘Subscriptions’, you can look up and (re)generate the key

How to add the subscription key to your request

When doing a request, include a header in the following format in your request

• Name: Ocp-Apim-Subscription-Key

• Value: Your subscription key value

Example

curl --location --request GET 'https://acc-api.edums.nl/account/v1/accounts' \
--header 'Ocp-Apim-Subscription-Key: 4f98695ca1f94abca21f5b5c34afa591' \

Bearer token

What it is

EduMS requires a bearer token to be included in the requests. This token identifies you as a user and indicates the access rights you have. You need your client id and secret to retrieve the token, you can see them as the username and password. You also need to include the subscription key when requesting the bearer token.

Each token is valid for 1 hour. Once it expires, request a new Bearer token before sending any further requests to API endpoints.

How to generate and use the token 

1. Navigate to the “POST bearer token” endpoint on the EduMS Identity API

2. Send the following body and replace the placeholders with the client-id and secret that you received.

grant_type=client_credentials&client_id=<REPLACE-WITH-CLIENT-ID>&client_secret=<REPLACE-WITH-CLIENT-SECRET>

3. If the client-id and secret combination match and are known you will get a 200 response with the following body:

{ 
"access_token": <your access token>, 
"expires_in": 3600, 
"token_type": "Bearer", 
"scope": <the scopes assigned to your client> 
}  

4. For further use in EduMS, you need to include the obtained token on your requests. You can do this by including it as a header in your calls in the following format:

• Name: Authorization

• Value: Bearer <your access token>

• config.headers.common.Authorization = `Bearer ${user.access_token}`