POST v3/credentials - Verify Credentials

Use this API to request updated user properties such as GUID, email, reference, and, most importantly, the user's access token to make subsequent requests on behalf of a user in the VitalSource Bookshelf ecosystem. This request can be made as either a single request or a bulk request by passing in multiple <credential> elements for each user.

VitalSource uses and enforces logical instance separation as one of many security measures to protect user accounts. Integrators can only access user accounts that were created or aliased by their own API keys.

For more information on users go to v3/users - Create



Data Definitions

Request can be done as a single request or in bulk by using multiple <credential> elements for each user.

Data Type
credential reference Message body Unique alphanumeric, often a student number or other identifier used by the integrators system. string  ABC_123_DEF_456 No
credential access-token Message body Unique token that allows you to perform SSO and content actions on behalf of a user in the VitalSource Bookshelf ecosystem string asdfcasdfge867sdf6sd7f8adsf No
credential email Message body  Email address used at registration if a full user. For reference users the non-addressable address sent in payload at create string  No 


Submission Matrix

Below is a mapping of which elements can be sent alone in order to request/verify credentials. This API will accept more than one credential(s) as part of a request.

User Type
Access Token
Reference user Yes Yes No
Full user Yes N/A No


Request Headers


Request body - reference user example

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
 <credential reference="{{variable_reference}}"/>

Request body - bulk example

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<credential reference="{{variable_reference}}"/>
<credential reference="{{variable_reference2}}"/>


Response body - reference user example

<?xml version="1.0" encoding="UTF-8"?>
<credential email=“" access-token=“numbersandlowercase” guid=“numbersandUPPERCASE” reference="yourReferenceID" email_verification_required="false" email_verification_completed="false">

Response body - bulk example

<?xml version="1.0" encoding="UTF-8"?>
<credential email=“"access-token=“numbersandlowercase” guid=numbersandUPPERCASE” reference=“bulk-test-101" email_verification_required="false" email_verification_completed="false">
<credential email=“" access-token=“numbersandlowercase” guid=numbersandUPPERCASE”" reference=“bulk-test-102" email_verification_required="false" email_verification_completed="false">

Response Descriptions

email Confirmation of email address created
access-token Used for subsequent calls related to this specific user.
It is important to use verify credentials before using an API call that requires an access-token to ensure you have the most current value.
guid Globally Unique Identifier in the VitalSource system.
reference Your system's unique reference id that is used to create the user. Should not be an email address.
email_verification_required Security feature


Error Codes

HTTP & Error messages 


Success. Errors provided simultaneously

Email or password was not accepted

When the username or password is not valid for the user in the request
601 Invalid access token reference When the access token is no longer a valid access token for a user. Rare error to occur, contact support for assistance.
603 Invalid reference value When the reference value does not exist in the VitalSource system, or was not created using this API key

Malformed credentials request

When credential password is not supplied along with email address in the request body
Insufficient permission to perform this action
Minimum required values must be submitted


Was this article helpful?
2 out of 2 found this helpful



Please sign in to leave a comment.