SCORM Cloud API Overview

Introduction

Lets start by going over some of the core basics of the API. For starters, the base path of the v2 api is:

https://cloud.scorm.com/api/v2/

As an example, probably the simplest call to test would be /ping. As a simple curl from the command line, that’d be:

curl -X GET https://cloud.scorm.com/api/v2/ping

Authentication

Now if you tested the /ping from the previous section, you saw that you got a 401 status code with the following response:

{ "error": "Authorization Required." }

All calls to the SCORM Cloud API require some type of authentication. This is where the app ID and secret key you noted earlier come into play. The SCORM Cloud API offers two types of authentication schemes: HTTP basic auth, and Oauth2.

HTTP basic auth

If you’re unfamiliar with how basic authentication works, you can take a detour to get up to speed with the MDN Documentation on the subject (we’ll wait here).

You’ll see this referred to as APP_NORMAL or APP_MANAGEMENT in our API specification. Your app ID will be your username and your password is your secret key.

OAuth2

You’ll see this as, you guessed it OAUTH, and it will be accompanied by a scope which is specific to the operation and endpoint you’re attempting to call. For instance, if you were looking to get a list of courses in your application, you’d request an OAuth token with the scope read:course.

We have two possible endpoints from which you can obtain authentication tokens. They are functionally exactly the same, with some small variance in what is returned. They are:

• POST /oauth/authenticate/application/token - Aliased as GetAppToken
• POST /appManagement/token - Aliased as CreateToken

A note on Application Management
In the ApplicationManagement Service you’ll find that that some of the endpoints require a special parameter childAppId, and have APP_MANAGEMENT as their basic authentication type. These endpoints require authentication with special App Management App credentials. The App Management App ID is not created by default. You can find or create the App Management AppId in the Apps tab of SCORM Cloud

Pagination

Several API endpoints return lists of data. There are often large amounts of records that need returned by these endpoints, which can result in significant network bottlenecks. In order to prevent these bottlenecks, list results are paginated, or returned in segments. For example, calls to GetRegistrations return “pages” of 10 registrations at a time. Each page will also include a more key. You can use the more key as a parameter to then fetch the next page of results and, if more results exists, the next more token. This process continues indefinitely until you stop making API calls or you reach the end of the registrations, at which point no more field will be present.

We also strongly suggest filtering your search results where possible. This cuts down on your API calls and how much data you need to parse. Filtering options are included in each endpoint’s Parameter section. You only need to pass filter options on the first API call as they will persist to subsequent calls that use more. So far we’ve successfully created an account, learned about our credentials, and how to use them to ping our application in an authenticated way.

Resources Overview

About Service

A simple service to get information about the server.

ApplicationManagement Service

The ApplicationManagement service provides an interface allowing you to both update existing applications (and their secret keys) as well as add/delete new applications. You may also retrieve OAuth2 tokens from the CreateToken method which can be used in future calls for authentication.

One thing that is important to be aware of:

For certain methods you’ll be required to authorize with an App Management application ID and secret key. Those methods are:

• getApplicationList
• createApplication
• deleteApplication
• getCredential
• createCredential
• updateCredential
• deleteCredential

Note:
The App Management application ID doesn’t exist by default. You can find or create the App Management on the Apps page of SCORM Cloud.

Authentication Service

This service has a sole method which will provide OAuth2 tokens. While the valid scope parameters are provided in the documentation for each of the methods, a list of the possibilities might be helpful.

Note:
One should be particularly careful with long lived tokens of significant privilege, as tokens may not be deleted or updated.

Course Service

The Course Service is where you’ll find methods for importing, previewing, configuring, and getting information on courses. Note that aside from preview, the course service is not used for launching courses. For that you should see the Registration Service.

Dispatch Service

This service provides an interface to SCORM Dispatch, a tool used to deliver SCORM content from SCORM Cloud to client LMSs in the form of a simple and highly compatible SCORM 1.2 package.

The three important entities to keep in mind when using the API are Course, Dispatch Destination, and Dispatch.

• A Course is any host course that has been imported under your AppId.
• A DispatchDestination should map to clients or locations where you’ll be sending your dispatches. In this way, dispatches can be enabled or disabled (or downloaded) per client / location.
• A Dispatch represents the intersection of a course and destination, and has the downloadable output of a simple SCORM 1.2 package that can then be launched at the given destination.

Centralization is the core of the dispatch concept. The dispatch package does not contain the course assets of the target course, it just gives access to the package hosted on SCORM Cloud. This means that a dispatch can be enabled or disabled at any time, and course corrections and updates will always immediately take effect, even after deployment of the dispatch packages. This allows the dispatch creator a high level of control from within SCORM Cloud.

Invitation Service

SCORM Cloud Invitations are an easy way to quickly deliver training to learners and track the results. After uploading your courses to Cloud, you can either publish a link to post anywhere you like or send emails to learners directly from SCORM Cloud. There are two types of Invitations:

Public Invitations

Public Invitations allow you to generate a link to your training. Then, anyone with access to that link can register in SCORM Cloud to take the course. Public Invitations can be set to either open or closed, have registration limits and/or expiry dates allowing you to control how many registrations are generated by the invitation.

Private Invitations

With Private Invitations you control who accesses your training content. Upload training to SCORM Cloud and use Private Invitations to email your courses directly to learners with a unique link for each specific learner. Registrations for Private Invitations are generated at the time the invitation is made. Each learner which is sent an invitation will generate a registration.

Learner Service

The Learner Service can be a little misleading in that learners don’t technically exist in SCORM Cloud. What we consider a ‘learner’ is simply the personal information about a learner that is on a registration. As such, the methods in this service are actually for acting on the personal information on registrations.

Tagging for learners can allow for SCORM Cloud to group registrations under these learner tags to generate reports based on those tags.

The deleteAllLearnerData method is largely for your convenience if your application receives a GDPR request.

Ping Service

This is a one method service which is a simple way to test your credentials, or verify that SCORM Cloud API is up and working.

Registration Service

This service provides calls for creating and removing registrations, and getting links for launching existing registrations.

Reporting Service

This service provides a set of methods for accessing information about or owned by the account designated by the appid, and ties in with the Reportage reporting application. For more information about accessing Reportage, check out the Reportage Integration Documentation.

xAPI Service

This service provides a simple interface to add and manage xAPI statement pipes. xAPI statement pipes provide the means to automatically transfer statements from one LRS to another.

Applications include:
- forwarding for users who wish to have their statements stored in their own Personal Data Lockers (PDLs)
- replicating production data in a sandbox LRS
- pulling data in from a remote LRS

There are 3 possible use cases of xAPI statement pipes, they are:

• Cloud Application to Cloud Application: For this you need to ensure that the source.url is pointed to the /statements endpoint, but the target.url is pointed to the base /lrs endpoint (with any extra endpoint information).
• Cloud Application to remote LRS: Ensure the source.url is configured as above, target.url pointed at the remote LRS.
• Remote LRS to Cloud Application: To pipe statements from an external source into SCORM Cloud’s LRS, then the target.url should be pointing to SCORM Cloud and specify the application ID, like it is in the example.