This is the developer reference guide to Boclips LTI implementation.

At the moment we support LTI 1.1 only.

Boclips LTI Features

Our current LTI implementation delivers read only views of resources:

  • videos,

  • collections of videos,

  • lists of video collections.

LTI is used here to authenticate external users within Boclips application. They don’t need to create accounts or log in, an LTI handshake does it on their behalf, making the experience seamless.

LTI protocol assumes that one web application will be opened from or within another web application. The aforementioned resources are thus plain web pages that display content to users. Whether that page is opened in a separate window or embedded within an iframe element is a matter of design preference.

LTI 1.1

In LTI 1.1 world, the two parties interacting with each other are:

  • tool provider — a service that has resources than can be accessed (consumed) using LTI. This is e.g. Boclips,

  • tool consumer — yourself, or any other party that wants to access Boclips content using LTI.

There is plenty of detailed documentation available on LTI (some of it linked below), but in a nutshell the simplest LTI workflow that we support looks like this:

  1. tool consumer executes an LTI launch request against the tool provider. It’s a HTTP POST request with some specific parameters,

  2. tool provider verifies the launch request (this is discussed further in following sections),

  3. if the launch request is valid, tool provider automatically provisions or retrieves a user account, establishes a HTTP session, sets a cookie and responds with a HTTP redirect to requested resource,

  4. tool consumer follows the redirect, passing previously received session cookie along,

  5. content is displayed to the end user.


Launch requests are verified based on a pre-shared set of credentials, consumer key and consumer secret. These are created by Boclips and exchanged with you before any integration can take place — they can be thought of as an equivalent of API keys.

An LTI 1.1 handshake works as follows:

  1. tool consumer collects all parameters required to execute a Launch Request,

  2. then it uses the secret to compute an OAuth 1.0 signature for that request. All POST parameters, HTTP method itself and request URL are included in signature generation,

  3. the signature is then attached as another POST parameter and the request is executed,

  4. upon receiving the request, tool provider removes the signature parameter, recomputes the signature and verifies the request,

  5. if the signature matches and all mandatory parameters are present, the request is deemed valid.

The key is passed as a part of a launch request and allows to identify different consumers. The secret should be stored in a secure manner and not be exposed to 3rd parties.

Anatomy of a Launch Request

All parameters mentioned below are transmitted as standard HTTP POST parameters.

LTI Parameters

A minimal subset of LTI launch request parameters required to access Boclips resources is presented in the table below.

Please note that LTI specification permits more parameters in order to pass contextual information along. Some parameters are treated as recommended, others are optional. Many recommended parameters include user information — this helps with automatic account provisioning.

More info on supported parameters can be found in official specification.

Parameter Type Optional Description




The type of LTI message as defined in LTI spec. For our case it’s a basic launch request and should be set to basic-lti-launch-request




The LTI version. Per spec it should be set to LTI-1p0 for LTI 1.1




Generated by the consumer, uniquely identifies the launch link that initiated an LTI launch within the consumer application

OAuth 1.0 Parameters

LTI 1.1 security model is based on OAuth 1.0 message signing. A well formed LTI launch request must contain all parameters listed below.

Ideally you won’t need to handle all of those yourself — there are open source LTI and/or OAuth 1.0 libraries available, for example we use an official IMS one for our JVM apps.

Parameter Type Optional Description




The LTI consumer key. We create it and give it to you as a part of credentials exchange




OAuth version, should always be set to 1.0




Signature method, should be set to HMAC-SHA1




The signature generated from request parameters and LTI consumer secret




Request timestamp, expressed in the number of seconds since January 1, 1970 00:00:00 GMT. More details here




A random value to help with uniquely identifying each request. More details here

Boclips Custom Parameters

We support additional parameters that allow customizing the LTI experience. They can be passed along all the other launch request parameters.

Parameter Type Optional Description




A URL to an image file that will be displayed at the top of LTI pages




A user ID which identifies the specific Boclips user interacting with LTI. This enables per-user analytics for backend clients.

Sample Launch Request

Below is an example of a valid LTI launch request issued using. Please note that the values below are just sample placeholders, not real parameters that can be used to execute a launch:

POST /v1p1/videos/5c542abf5438cdbcb56df0bf HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: lti.boclips.com


The server responds with a redirect to the resource and sets a session cookie:

HTTP/1.1 303 See Other
X-XSS-Protection: 1; mode=block
Via: 1.1 google
Set-Cookie: SESSION=YjllM2M4YWQtZjI4Yy00YTIzLWEwZGYtOGU0M2Q1YWExMWYw; Path=/; Secure; HttpOnly; SameSite=None
Location: /videos/5c542abf5438cdbcb56df0bf
Alt-Svc: clear
Given our current LTI implementation, the launch requests will look nearly the same for other resource types. Only the resource URL will change.

Resource Endpoints

Single Video

Displays a single video playable using our interactive player.


Collection of Videos

Displays a collection of videos with thumbnails and descriptions. Clicking on any of them will take the user to a video page.


List of Collections

Displays a list of available collections with a subset of video thumbnails for each of them. Selecting one of them will take the user to a video collection page.

Note that the assumption is that IDs of resources are known in advance and as a consumer you embed LTI links them as you choose. Alternatively, users can explore the full content library from the collections list page (last resource).

External Resources

Below are a mix of official LTI docs from IMS and articles written by developers that can prove useful when implementing LTI capabilities.