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

Verb/URI

POST https://api.vitalsource.com/v3/credentials.xml

Data Definitions

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

Name
Usage
Description
Data Type
Example
Required
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  sri.krisha@univ.edu  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
Email
Reference user Yes Yes No
Full user Yes N/A No

 

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS

Request body - reference user example

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

Request body - bulk example

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

Response

Response body - reference user example

<?xml version="1.0" encoding="UTF-8"?>
<credentials>
<credential email=“lettersandnumbers@placeholder.23332.edu" access-token=“numbersandlowercase” guid=“numbersandUPPERCASE” reference="yourReferenceID" email_verification_required="false" email_verification_completed="false">
</credential>
</credentials>

Response body - bulk example

<?xml version="1.0" encoding="UTF-8"?>
<credentials>
<credential email=“lettersandnumbers@placeholder.23332.edu"access-token=“numbersandlowercase” guid=numbersandUPPERCASE” reference=“bulk-test-101" email_verification_required="false" email_verification_completed="false">
</credential>
<credential email=“lettersandnumbers@placeholder.23345.edu" access-token=“numbersandlowercase” guid=numbersandUPPERCASE”" reference=“bulk-test-102" email_verification_required="false" email_verification_completed="false">
</credential>
</credentials>

Response Descriptions

Name
Description
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
email_verification_completed  

 

Error Codes

HTTP & Error messages 
Message
Notes
200

 

Success. Errors provided simultaneously
466

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
650 

Malformed credentials request

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

 

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

Comments

0 comments

Please sign in to leave a comment.