2) Bookshelf workflow - v3/credentials - Verify

This step, Verify should go before 3) Bookshelf workflow - v3/users in your code. Make sure your user creation setup is working in and of itself, then place this step (verify) first.  

Prior to performing any transactions on behalf of a VST user; it is a best-practice to encode v3 /credentials - Verify as a double check. This endpoint will return the current valid credentials for any user account you are authorized to access. 

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.

Let us examine the following use-cases:

• Verify: You possess all the credentials but wish to re-confirm these details
• Reference User: You only have your reference string (passed at create)

Verify

The primary use for this endpoint is to verify credentials and such it is designed to accept minimal credential elements while returning complete credentials. The uniting security feature is that this functionality is only available for user accounts created by the API key you connect to the service with.

In order to work with our services on behalf of a user it is often necessary to possess their access token. You can use a stored access token to call POST v3 /credentials - Verify to verify that the user remains valid with the service.

To perform this action you will need:

• A valid API key
• The reference string passed at Post v3/users - Create

Below is a curl statement to work with this endpoint

curl -X POST \https://api.vitalsource.com/v3/credentials.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"

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

Successful response will include:

• Current user access token and GUID

<?xml version="1.0" encoding="UTF-8"?>
<credentials>
   <credential email="something_test@test.com" access-token="ce9fff409c89d62d598b9ce4668" guid="84CFTPG7DT7AZEEJ" reference="">
   </credential>
</credentials></licenses>

If the call fails we will send XML containing a description of the failure and an custom code. With the documentation of every endpoint you will find a list of any http codes associated with that service. I.e. error code 601 = When the access token is no longer a valid access token for a user.Our service responds with http error codes. You will always receive 200 upon success, which in the case above means that your access token remains valid.

Should your receive this error (601), you should generate a new token for this user at POST v3/users/reset_access - Reset Token

 As this is a bulk or single endpoint it is possible to query this endpoint with up to 10,000 records at once with few discernible performance issues. 

Reference User

The occasion may arise when you only have the internal reference string associated with the user account but possess no other identifying mechanisms connected to the underlying VitalSource reference account. Using only this string (which must be unique to each reference user you create,) is enough to work with the v3 /credentials - Verify endpoint. It is important to note that the reference string association is tied to the underlying API key, so you must use the same key that was used to create this user.

To work with this endpoint you will need:

• The same API key used to create this reference account
• The unique reference string you passed VitalSource upon creation of the reference account

Below is a curl statement to work with this endpoint

curl -X POST \ https://api.vitalsource.com/v3/credentials.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"

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

 Successful response will include:

• Reference account access token and GUID

<?xml version="1.0" encoding="UTF-8"?>
<credentials>
  <credential email="9121765dc091@placeholder.23332.edu" access-token="853e28c6779114e0" guid="VJFVDHHH8YK65NAN" reference="test_create_02">
  </credential>
</credentials>

Now that you have verified the users credentials you are ready to work on behalf of a user. The next step in the Bookshelf workflow is Bookshelf workflow - fulfillment
If the call fails we might send error code 603 = When the reference value does not exist in the VitalSource system. Should your receive this error (603), you should make a new account at Post v3/users - Create