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 password Message body Current user password from VitalSource Bookshelf string Password conforming to current VitalSource standards 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
Password
Reference user Yes Yes No N/A
Full user Yes N/A No No

 

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS

Request body - reference user example

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

Request body - full user example (legacy customers only)

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<credentials>
 <credential password="{{variable_PW}}" access-token="{{variable_access_token}}"/>
</credentials>

Request body - bulk example

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<credentials>
<credential reference="{{variable_reference}}"/>
<credential access-token="{{variable_access_token2}}" 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 - full user example (legacy customers only)

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<credentials>
 <credential email="sri.krisha@univ.edu" access-token=“numbersandlowercase” guid=numbersandUPPERCASE” reference="" email_verification_required="false" email_verification_completed="false">
</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.
This may expire; see reset token
guid Globally Unique Identifier in the VitalSource system. VitalSource strongly recommends all integration customers save this field in the response payload. As we provide the ability to update all elements, including reference and your access token may change, GUID may be the only way to recover access to a user. GUID will never change.
reference Answer back of your reference
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. Please visit v3/users/reset_access - Reset Token
603 Invalid reference value When the reference value does not exist in the VitalSource system, or was not created using this API key
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.