If you operate an online service or web application, it is likely that your users will have a user account with your service. It is possible for your existing users to navigate to OpenLearning Classes where they will be already signed in with the same identity, without requiring a second login.

This guide demonstrates how OpenLearning can be used as a course provider for your application, and how you can use the OpenLearning API to:

• Provision managed OpenLearning user accounts for your existing users
• Generate launch links to authenticate their accounts with OpenLearning

Note that this process is the same as using LTI for sign on, only the OpenLearning API can be used as a shortcut for generating the launch parameters.

The general flow is as follows:

  

 

You will need:

• An OpenLearning account which is an administrator role for an Institution Portal
• An API Key for this account (a new one can be generated here). This guide will use the value "your-api-key" as a placeholder. This key is a bearer token used for server-to-server requests. It should be kept securely on your application server and never revealed to any client code.
• Your Institution Portal ID (see Note 1. below). This guide will use the value "your-institution-id" as a placeholder
• The OpenLearning Class ID (see Note 2. below) for each OpenLearning class (in which your users are to be enrolled)
• Familiarity with making GET and POST requests to APIs from within your application software

 

Note 1: Finding your Institution ID

Provided you have already generated your API Key, you can list all institutions for which this account is a member by making a GET request to the /users/{user_id}/institutions/ API. This will include each Institution ID.

e.g.

GET https://api.openlearning.com/v2.1/users/me/institutions/?api_key=your-api-key

 

Note 2: Finding Class IDs

Each OpenLearning Course setup can deliver multiple classes (a “class” is an instance of OpenLearning course content for a particular delivery or time period). Given the OpenLearning URL of a course, a GET request to the /courses/ API can be used to find the corresponding OpenLearning Course ID.

e.g. (to find the ID for https://www.openlearning.com/courses/my-course)

GET https://api.openlearning.com/v2.1/courses/?url=https%3A%2F%2Fwww.openlearning.com%2Fcourses%2Fmy-course&api_key=your-api-key

For each OpenLearning Course ID, each of its classes can be listed using a GET request to the /courses/{course_id}/classes/ API. This will provide the class IDs required by your application. It is up to your application how to store enrolments  (which user accounts have access to which class IDs).

e.g. (to find the classes for a course with the ID "your-course-id")

GET https://api.openlearning.com/v2.1/courses/your-course-id/classes/?api_key=your-api-key

 

1. Provisioning Managed OpenLearning User Accounts

All user accounts within your application will need have a matching linked user account on OpenLearning before a launch link can be generated. The /institutions/{institution_id}/managed-users/ API can be used to create OpenLearning user accounts which are managed by your institution. 

This API creates "managed" user accounts, which means that institution administrators have special control over these user accounts, regarding password resets and the updating of user information (including the ability to specify an institution-wide student identifier for this account).

1.1 External Institution IDs

OpenLearning accounts will be created by this API on your user’s behalf. These will be the user accounts for each of your users within the OpenLearning platform, and linked to each of your application’s user accounts using an external institution ID. The external institution ID is a value used by your application to uniquely identify each user (e.g. an account ID, a student number, or a uniquely identifying user email address).

1.2 API Request Parameters

A POST request to this API will provision a new user account on OpenLearning, given that it is provided the following as x-www-form-urlencoded parameters:

• The user’s full name (full_name)
• The user's external institution ID (external_institution_id)
• The user’s primary contact email address (primary_email_address)
• [optional] The user’s profile image (profile_image) may also be specified as an image URL

Additionally, the following parameters should be set to false:

• send_password_email, to prevent an email being sent to the user with an OpenLearning account password
• send_welcome_email, to prevent sending the user the standard OpenLearning new account creation email

e.g.

POST https://api.openlearning.com/v2.1/institutions/your-institution-id/managed-users/?api_key=your-api-key
Headers:
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Body:
full_name=User%20Name&external_institution_id=external-id-for-user&primary_email_address=user%40example.com&send_password_email=false&send_welcome_email=false

1.3 Important API Response Data

Upon making the POST request to provision a new user account, the server will respond with the OpenLearning User object for the newly created account. This object contains the OpenLearning User ID, which should be stored within your application for the respective user account. This value is required later in order to generate launch links for each user.

1.4 When to Make the API Request

This request must be performed before an authenticated launch link can be created. It will therefore need to be made:

• Once to provision an OpenLearning account for all existing user accounts within your platform
• Once for each new user registration to your application

2. Generating Authenticated Launch Links

Your application can generate authenticated launch links for its user accounts, once they each have a matching linked account within OpenLearning. A launch link is a POST request made by your application client to an OpenLearning server to initiate the single sign on.

The POST request URL and data is generated via the OpenLearning API each time a user needs to navigate from your application to an OpenLearning class. The /institutions/{institution_id}/managed-users/{user_id}/sign-on/ API can be used by your application server to generate the required launch request. This data is sent to your application’s client for it to fulfil, which in turn launches OpenLearning as the authenticated user, with access to the required OpenLearning class.

2.1 API Request Parameters

A POST request to this API will generate the launch link’s request data, given that it is provided:

• OpenLearning User ID (user_id, provided as the “id” field in the response referenced in section 1.3).
• OpenLearning Class ID (class_id, the OpenLearning Class to launch, in which the user should be enrolled and given access within OpenLearning)

2.2 API Response Data

The server will respond with three key/value pairs:

• "url" - the URL to which the application client will make the POST request
• "method" - this will be “POST”, indicating that a POST request is to be made by the client
• "params" - this is an object where each key/value pair corresponds with a x-www-form-urlencoded POST parameter to be sent in the request body

2.3 When to Make the API Request

Launch links include an expiry time and must be generated each time your application needs to provide authenticated user navigation to an OpenLearning Class.

Upon your application client receiving the launch link data for the current user, a POST request will need to be made by the application client, and the user will be taken to the required OpenLearning Class. The user will be automatically signed in as their current user identity, and given access to this class (if they were not enrolled previously).

3. Example Scenario

Your application will be referred to as "the Application":

• the Application Server - your web application server
• the Application Client - your web application client, e.g. running in the user's browser

Operations which are part of the Application are coloured blue. Operations which take place on OpenLearning are coloured green.

1. A new user ("the User") registers on the Application Server, and a new Application user account is created
2. The User, or an administrator of the Application, uses the Application to enrol the User in an OpenLearning Class ("the Class"), for which the Class ID is already known. The Application Server stores an enrolment relationship between the User's Application account, and the OpenLearning Class ID for the Class.
3. The Application Server makes an API request to the OpenLearning API to provision an OpenLearning User Account for the User. The User's Application user account stores the resulting OpenLearning User ID. If the User already exists as an OpenLearning User, this operation has no effect.
4. The User, using the Application Client, wishes to start their OpenLearning coursework in the Class and navigates to the course entry point within the Application Client.
5. The Application Server makes an API request to the OpenLearning API to generate a launch link which will give the User access to the Class on OpenLearning.
6. The Application Client fulfils the launch request, using the launch information provided by OpenLearning to make a POST request to OpenLearning.
7. This navigates the User to the Class homepage on OpenLearning, ensuring the User has access to the Class, and is automatically logged in to their OpenLearning account.