Most of the Storefront API endpoints do not require authentication as they only respond with public information.
However, some sections such as account or checkout do require some form of authentication:
- Time-limited user authentication token obtained from our OAuth server (only signed-in users)
- Order token that allows you to perform operations on the cart and checkout for that order
User tokens
Login
Let's create a new token for a user with the email [email protected] (If the user does not exist, it will be created).
curl --request POST \
--url https://demo.getvendo.com/api/v2/storefront/auth \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"user": {
"email": "[email protected]"
}
}
EOF
You can also specify first and last name that will be used if the customer does not exist
curl --request POST \
--url https://demo.getvendo.com/api/v2/storefront/auth \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"user": {
"email": "[email protected]",
"first_name": "Vendo",
"last_name": "Demo"
}
}
EOF
You should receive a JSON response:
{
message: 'Code sent'
}
The customer should now receive an email with the OTP code that you should send as code parameter to receive the access_token
curl --request POST \
--url https://demo.getvendo.com/api/v2/storefront/auth \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"user": {
"email": "[email protected]",
"code": "123456"
}
}
EOF
You should receive access_token and refresh_token as a response
{
"access_token": "Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98",
"token_type": "Bearer",
"expires_in": 2678400,
"refresh_token": "j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY",
"created_at": 1581876572
}
As you noticed the token is time-limited. It also comes with a refresh_token which you'll need to use to (you guessed it) to refresh the token:
curl --request POST \
--url https://demo.getvendo.com/api/v2/storefront/auth \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"user": {
"email": "[email protected]",
"refresh_token": "j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY"
}
}
EOF
And this will return the same format JSON response (but with different access and refresh token):
{
"access_token": "Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98",
"token_type": "Bearer",
"expires_in": 2678400,
"refresh_token": "j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY",
"created_at": 1581876572
}
Now you can start using these tokens, eg. fetching the account information:
curl --request GET \
--url https://demo.getvendo.com/api/v2/storefront/account \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98'
You need to pass access_token as Authorization: Bearer <access_token> in your headers.
You can use the user token with any endpoint, eg. when creating a cart with a user token it will auto-assign this cart to the user. Also when fetching products with user tokens you will receive per-user pricing (if configured).
Logout
If you want to revoke an access token, you can send a DELETE request with the access token, like presented on this example
curl --request DELETE \
--url https://demo.getvendo.com/api/v2/storefront/auth/Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98 \
--header 'Accept: application/vnd.api+json'
You can also revoke a refresh token by passing refresh token instead of access token
curl --request DELETE \
--url https://demo.getvendo.com/api/v2/storefront/auth/j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY \
--header 'Accept: application/vnd.api+json
Order tokens
Order tokens are used to access the cart and checkout for a specific order. To create a token you need to create new Order (cart):
curl --request POST \
--url https://demo.getvendo.com/api/v2/storefront/cart \
--header 'Accept: application/vnd.api+json' \
--header 'Content-Type: application/vnd.api+json'
This will return JSON response:
{
"data": {
"id": "d2a9f08a-81de-42ec-99c5-9f5893291336",
"type": "cart",
"attributes": {
"number": "R233871560",
"item_total": "0.0",
"total": "0.0",
"ship_total": "0.0",
"adjustment_total": "0.0",
"created_at": "2022-09-28T22:15:07.471Z",
"updated_at": "2022-09-28T22:15:07.471Z",
"completed_at": null,
"included_tax_total": "0.0",
"additional_tax_total": "0.0",
"display_additional_tax_total": "$0.00",
"display_included_tax_total": "$0.00",
"tax_total": "0.0",
"currency": "USD",
"state": "cart",
"token": "zTEpsukRq_yEUcXVCSv0uw1632867307450",
"email": null,
"display_item_total": "$0.00",
"display_ship_total": "$0.00",
"display_adjustment_total": "$0.00",
"display_tax_total": "$0.00",
"promo_total": "0.0",
"display_promo_total": "$0.00",
"item_count": 0,
"special_instructions": null,
"display_total": "$0.00",
"pre_tax_item_amount": "0.0",
"display_pre_tax_item_amount": "$0.00",
"pre_tax_total": "0.0",
"display_pre_tax_total": "$0.00",
"shipment_state": null,
"payment_state": null
},
"relationships": {
...
}
}
}
The most important is the token attribute (data['attributes']['token']) which we will use from now on to authorize API calls for this order, eg.:
curl --request GET \
--url https://demo.getvendo.com/api/v2/storefront/cart \
--header 'Accept: application/vnd.api+json' \
--header 'X-Vendo-Order-Token: zTEpsukRq_yEUcXVCSv0uw1632867307450'
You need to use that token in a header called X-Vendo-Order-Token. That's it!
Remember that after completing the checkout you need to create new cart and obtain a new token!