3) Bookshelf workflow - v3/users

Two types of users exist within the VitalSource Bookshelf ecosystem:

Reference users

• No password or email associated with the account
• Eliminates the need to pass identifiable information to VitalSource
  • First and last name are required fields, but these are strings so you can pass hashed or dummy data
• VitalSource can still support full user accounts via a forced upgrade process (described in detail here)

Full users

• Not described here. Full user accounts are only supported in legacy integration setups. Please speak with an integrations manager for more information.
• Full users should direct register with VitalSource at https://bookshelf.vitalsource.com

Reference Users

To create a reference user account you only need to pass the following:

• First and last name (string fields, you can pass hashed data). First and last name are needed for sharing features only.
• Your reference string, this should be your internal identifier for this user (I.e. student ID, employee ID, customer ID.) You should always use your reference ID to locate the user.
  • Reference string can be modified via v3/users/:param - Update
  • Integrators should always store the GUID received from VitalSource in payload during create, as this will not change

You will POST these (minimum) elements to the v3/users - Create endpoint.

Below is an example curl statement that you can paste into a terminal window:

curl -X POST \
 https://api.vitalsource.com/v3/users.xml \
 -H 'Accept: */*' \
 -H 'Host: api.vitalsource.com' \
 -H 'X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE' \
 -d '<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<user>
   <reference>fakename_create_01</reference>
   <first-name>John</first-name>
   <last-name>Citizen</last-name>
</user> '

A successful response will include:

• Placeholder.###.edu email address
  • This is a non-modifiable and non-addressable field on a reference account
• User first and last name
• User access token and GUID
  • GUID will not change, store this element
  • Access tokens may be reset by integrators or VitalSource

Below is the response from the curl statement.

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<user>
    <email>18e63065f017c56@placeholder.23332.edu</email>
    <first-name>John</first-name>
    <last-name>Citizen</last-name>
    <guid>VMN2WW3GRDYUV2B</guid>
    <access-token>0dceddfb841f601b6966f6fd1</access-token>
    <library></library>
</user>

The next step is to use Bookshelf workflow - v3/credentials - Verify  and verify that the account you have created is valid. It is worth pausing to note the library response above. By default the API will respond with an array of all content that this user has access to, including any content redeemed during the creation of the account.