POST LTI: Create a Bookshelf Launch

This API will accept POST requests in IMS Global LTI 1.0 format using VitalSource Launch as the LTI tool.

Example Launch from the IMS Global Specification

VitalSource Launch will consume your request, provision the VitalSource Bookshelf user account, add the book your are passing and respond with an SSO URL that will open this user account, at the location you seek.

To complete this request you MUST be previously setup in VitalSource Launch by an Integrations Mgr.

LTI 1.0 relies upon oAuth 1.0 as the authentication protocol. You must utilize this mechanism when making an LTI request. Below we are describing how to complete this request using Postman, but other development environments are acceptable. Your request header must contain an oAuth 1.0 HMAC-SHA1 authorization. This will include the VitalSource Launch Key and VitalSource Launch Secret sent to you by the Integration Mgr who set you up at VitalSource. As a separate item in the request header you will also need to pass "X-VitalSource-API-Key" which is the API key that allows you to make RESTful requests to VitalSource.

The Postman example can be found here

Verb/URI
Data Definitions
Request Headers
- Request header - default example (using urlencoded)
Success
Failure

Verb/URI

Options depending on integration:

POST https://bc.vitalsource.com/books/[vbid]
POST https://bc.vitalsource.com/books/book

Data Definitions

Name	Usage	Description	Data Type	Example	Required
user_id	Query param	Uniquely identifies the user. This should not contain any identifying information for the user.	string	XQAvw178fejlkw9044	Yes
roles	Query param	LTI role in this context. Note: Instructor launch will change the presentation within VitalSource Bookshelf.	string	Learner, Instructor, Administrator, TeachingAssistant, ContentDeveloper, and Mentor	No, Highly recommended
launch_presentation_document_target	Query param	This field communicates the kind of browser window/frame where the TC has launched the tool.	string	frame, iframe or window	Yes
custom_vbid	Query param	The custom book identifier for SSO. This sends a user directly to a piece of content.	string	L-999-70103	No
custom_book_location	Query param	Allows the redirect to take a user to a "deep link" or specific location in the content.	string	Open the book in Bookshelf. Find the page you wish to link to. In the lower right corner is a Copy URL icon (look for the paperclip). Copy the portion from "epubcfi" on. e.g. epubcfi/6/30[idloc_014.xhtml-itemref]!/4[eid11382]/18[eid11625]/12[eid11691]/8[eid11696]@0:65.6	No
context_id	Query param	Value for the context of a launch, could be a course code, section number something unique to the calling system	string	A123B456C789	Recommended
context_type	Query param	This string is a comma-separated list of URN values that identify the type of context	string	CourseSection	No
context_label	Query param	A label for the context	string	ENG101-01	No
context_title	Query param	A title of the context	string	English 101	No
lti_version	Query param	This indicates which version of the specification is being used for this particular message.	string	LTI-1p0	Yes
lti_message_type	Query param	This indicates that this is a Basic LTI Launch Message.	string	basic-lti-launch-request	Yes
lis_person_name_full	Query param	User full name	string	Test User	No, not required by VitalSource
lis_person_name_family	Query param	User last name	string	Test	No, not required by VitalSource
lis_person_name_given	Query param	User first name	string	User	No, not required by VitalSource
lis_person_contact_email_primary	Query param	User email	string	test.user@school.edu	No, not required by VitalSource
tool_consumer_info_product_family_code	Query param	Your product name	string	PostmanRequest	No

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS
Content-Type: application/x-www-form-urlencoded
Accept: application/html

Request header - default example (using urlencoded)

Success

HTTP: 200

A success will redirect the user automatically into the bookshelf account and book specified including the other specific parameters around deep link or presentation method.

Failure

HTTP Code: 403 Forbidden

See full list of error codes and messages.