Creating a typical LMS integration

Drillster lends itself very well for integration into third party learning management systems (LMS). This way Drillster's adaptive memorization and testing capabilities can greatly enhance an integrated learning environment.

  • Practice drills and do tests as regular learning activities inside the LMS
  • Keep track of the proficiency levels and progress of your students
  • Provide a seamless integration between Drillster and the host platform


The following things are required in order to make the integration work with an LMS as described in this document:

  • Drillster Education or Business license or Premium account – The connection between the LMS and Drillster makes use of Drillster's group functionality, which requires a paid account. Also, the integration will automatically add user accounts to groups in case no corresponding Drillster account exists for the LMS user. For premium accounts the maximum group size is limited. For license accounts no limits on group sizes exist.

  • A main account with appropriate permissions – There will be at least one main account in Drillster one whose behalf the API calls will be made. This account should have the appropriate permissions to manage groups and to create user accounts. Also, the organization linked to the account must be configured such that user can be added to groups with prior permission from those users. Please contact Drillster Support if you are not sure whether your account is set up correctly.

  • Internet access ‐ This one sounds like a no-brainer, but it is very important. The LMS instance should have outbound access to (ports 80 and 443). This will allow it to make the appriopriate API calls. The LMS users who will be using Drillster learning activities must have access to in order to access those learning activities. For drills containing audio or video, additional hosts are accessed. In most educational or business environments this is no problem. In general, any modern browser with internet access (direct or proxied) will do just fine.

The flow described here relies on the ability to keep the administrative OAuth token (and associated client secret) a secret from the end user. This means that a server side component is required, and that for instance a pure Javascript implementation that runs inside the learner's browser cannot be made to function securely.

A typical integration consists of a couple of components:

The aim of this document is to provide guidelines and best practices for making such an LMS integration. It is by no means an exhaustive description of what sort of integrations are possible. Also, this document assumes that the actual drill content will be created in Drillster by administrators of the LMS. There are ways to automate the loading of drill content, but that is beyond the scope of this document.

Connecting to the Drillster API

In order to create user accounts in Drillster, facilitate a seamless login or to retrieve proficiencies, an API connection between the LMS and Drillster must be created.

Drillster has a REST API that uses JSON as the data protocol. Authentication is done using the OAuth 2.0 mechanism. The use of OAuth means that API requests can be made on behalf of a Drillster user account as and when that user has given permission to the 3rd party system to access the account.

In a typical LMS integration, the API requests are usually not directed at the individual user accounts, but rather at an administrative account in Drillster. This greatly simplifies things, as only a single account authorization is required.

Two scenarios

When it comes to authentication with Drillster in LMS integrations, there are usually two scenarios:

  1. There is only a single instance of the LMS – In case of a single instance, the integrator can simply register an API client to obtain a client ID and client secret. These credentials may be included in the integration. This usually simplifies the integration.

  2. There are multiple instances of the LMS – For LMS system that are sold to companies or schools it is possible to create an integration that allows administrators of the LMS to link their LMS instance to their own administrative Drillster account. In other words: the LMS administrator registers a client application with Drillster, obtains their own client ID and secret and must have the ability to enter these details into the integrating component. This allows for a single integration module to serve multiple independent connections to Drillster.

If there is just a single instance of the LMS, it is probably easiest to let Drillster Support register the application, and generate the client application credentials.

Please be aware that non-expiring OAuth tokens are no longer supported. Generated OAuth tokens have a limited validity, but are always accompanied by a refresh token so that a new token may be obtained. See our OAuth documentation for more information.

In all cases, the integration must be able to authorize a Drillster account for a client application, and be able to automatically refresh OAuth tokens using a refresh token. Please refer to our OAuth documentation to learn how to build such an integration.

Automatically setting up user accounts

Drillster is all about long term retention of knowledge. This means that it is imperative to track individual user progress, and in order to do that, a user account must exist in Drillster for each LMS user that needs to make use of Drillster functionality.

To set up a user account, just two things are required:

  1. The user's real name
  2. The user's email address or a previously agreed third party ID

Drillster does not use the email address as the primary key for the account, but assigns a unique alphanumeric user ID to each account. This user ID is returned in the response of the API call. It is entirely possible that the user changes her email address in Drillster, or adds additional email addresses to the account. Even the name can be changed by the user, but the user ID will remain constant.

Another possibility is that the user already exists in Drillster. The user could have a pre-existing account, or the LMS may not have recorded that it set up the account earlier. This is no problem, but it is important that the LMS deals with exception correctly.

Assuming that a valid OAuth token is available, the LMS can set up a new user by sending a PUT request to with a JSON document containing the details for the new user. For example:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k
  "emailAddress": "",
  "name": "Jane Doe"

It is possible to include the locale and time zone for the new user as well. If these values are omitted, they are copied from the stored values for the account on whose behalf the API call was made. This means that unless you specify a locale and/or timezone in your request, all users you set up will be in the same locale and timezone as the administrative Drillster account.

A successful response would have an HTTP response code 200 and returns the generated user ID as follows:

  "userId": "7qr6JFBZR27rLMXiqX0srg"

If the user already exists, an error response is returned with HTTP response code 400 (Bad request). The response does contain the user ID:

  "id": "exists",
  "description": "User already present",
  "userId": "7qr6JFBZR27rLMXiqX0srg"

It is important to pick up the user ID in either case, as it is required in order to add this user to the appropriate groups.

For exact details about this API endpoint, please see the specification of the API's user endpoint.

Adding users to groups

Drillster's groups provide the mechanism to allow access to predefined sets of drills or tests to a group of users. A group in Drillster in its simplest form is a collection of drills assigned to a collection of users. Once learning material is structured in groups, it becomes possible to set learning objectives, assign tests and to run various reports. Drillster's groups mechanism lends itself extremely well for integration with an LMS.

For the scope of this document it is assumed that the groups have already been created and filled with content (i.e. the drills or tests). Groups can be created in Drillster by the administrative user. It is also assumed that the LMS has knowledge of the group codes (unique IDs for each group) relevant for each user. This should probably be part of the course building process where a Drillster learning activity is included in the LMS.

In order to add a user to a group, the following information is required:

  • A valid OAuth token. The same token used to create the user account can be used here.
  • The group code. Group codes can be obtained from the Drillster website, where groups are created and managed.
  • The user ID. This is the ID that was obtained from the PUT user API call.

The user is added to the group as follows:


Or, with some example codes:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k

A successful response would have an HTTP response code 200 and returns a message stating that:

  "id" : "added"

If the user was already part of the group, an HTTP response code 400 will be returned, with the following message:

  "id" : "already_member"

Note that it is important to separate this error from other errors, as it still signifies a positive result!

By adding the user to the group, the user now has access to all of the drills and tests contained in the group. Should the user log in into the Drillster website, he or she will see all of the drills from the group listed in the repertoire. These drills do not count toward the storage limit of a basic user account. Any drills that are added to the group later will immediately be available to all current group members.

It is possible to remove users from a group through the API as well, but that is beyond the scope of this document. For exact details about this API endpoint, please see the specification of the API's group/…/members endpoint.

Requesting user access

The next step in the integration is to provide a seamless experience for the user. If users are presented with a player widget in the LMS, Drillster does not know who that user is, unless they have logged in before. This means that Drillster will ask the user to log in, which is far from a seamless user experience. In fact, for users that have just been added through the API, there is no password set, so users are unable to log in until they request a password.

Delegated user logins provide a way for a third party to integrate Drillster into another product by way of automatically establishing a logged in user session on Drillster. That way users authenticated on the host system do not have to log in into Drillster. In fact, these users do not even have to know their Drillster credentials.

From a high level, the mechanism works as follows:

  1. The LMS system sends an authentication request for a given user ID to the Drillster API.

  2. Drillster checks that the user making the API call has the permission to let the requested user in into Drillster. In practice this means that the proxied user must be member of a group for which the calling user has administrative rights.

  3. If permissions are OK, Drillster will respond with a message containing a URL and a unique token. The token acts as a one-time login for that user.

  4. The LMS system is then able to embed widgets with a fully authenticated session by adding the token as an attribute to the code to load the player widget. Note that strictly speaking this is not a “single sign-on” solution, but rather a delegated (or proxied) login. Once an authenticated session has been established for the user, further tokens are ignored.

An access token can be retrieved by having the LMS make the following GET request:


Or, with some example data:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k

An example of a typical response:

  "url": "",
  "token": "l1ko49urumvkgnZ8"

The token should be picked up from the response message, and used as a drl-token attribute in loading the Drillster player widget or other widgets.

For exact details about this API endpoint, please see the specification of the API's access endpoint.

Presenting drills to your users

Once a user ID has been established, the user is part of one or multiple groups, and an access token has been generated, it is time for some user interaction. You can display any test or drill widget to your users by embedding the Drillster player on the page. Please see our widgets documentation for details on how to display Drillster widgets on your page, and how to include the session token.

For the scope of this document, it is assumed that the LMS has knowledge of the drill codes that are part of the group. The only variable part in the embed code is the drill code, so the URLs are easy to generate.

A typical embed code for a player widget looks like this:

<script src="" type="text/javascript"></script>
<div class="drl-widget drl-player" drl-code="CZ_nPz74RJ2zFotkYzaUJw" drl-token="l1ko49urumvkgnZ8"></div>

Again, please refer to our widgets documentation for details about the use of the widget loader and customization options.

If you are unable or unwilling to store the user ID beforehand, it is possbile to execute the three steps described above in rapid succession as and when you are looking to present a test or drill widget to a user. This means: ① create the user (or determine the user ID from the response if the user is already present), ② add the user to the group, ③ request an access token, ④ present a test or drill widget to the user with the token included.

The player widget is able to open tests as well as drills. Embedding these works in exactly the same way. The test keys can be extracted from the group detail screen in the Drillster application. The test key is the same for each group member.

Receiving push messages

In addition to interacting with the Drillster REST API, it is also possible to subscribe to certain events. Upon these events occurring, Drillster can push an event message over HTTPS to your LMS. This requires configuration on the side of Drillster. Please see the push API documentation for details.

Content upload

For getting your content into Drillster in a semi-automated way, it is possible to run CSV file uploads through the user interface. The best results are achieved with a UTF-8 character encoding. If you are using MS-Excel to export spreadsheets to CSV format, please select the “Windows text” CSV variant.