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
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
|
|---|---|
| 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 |
| 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 |
Comments
Please sign in to leave a comment.