Building a headless ecommerce means setting up communication between your frontend and VTEX's REST APIs. Each HTTP request sent from your frontend to VTEX must be authenticated with a user token. The implementation shown below describes how to obtain this token in your application.

This feature is currently being tested by a limited number of VTEX accounts. Please do not share this documentation with people outside of your operation.

To ensure a secure shopping experience, shopper authentication for headless VTEX stores must follow a specific flow, as presented in the following:

1. The shopper authenticates themselves in your frontend via an OAuth integration.
2. Your frontend exchanges the OAuth identity provider access token for a VTEX user token.
3. Now, with the user token previously obtained, your frontend application can make API requests to VTEX and access all the necessary information to perform actions on behalf of the shopper.

Below you can learn more details on each of these steps.

When building a headless store, you are opting to use a frontend application different from VTEX's native frontend. Hence, you must adhere to the guidelines provided below and be aware of your application's responsibilities in order to ensure a smooth and secure shopping experience for your customers.

Shopper authentication in your headless store must happen through an external identity provider. To do this, you must set up a custom OAuth login integration.

Headless authentication scenarios require using a custom OAuth login integration. The native social authentication settings described in the Configuring login with Facebook and Google guide don't apply to headless authentication.

After you have configured your OAuth connection in the VTEX Admin panel, you can implement the OAuth login on your frontend, according to your store's needs and responsibilities.

Make sure that the OAuth access token has scope email (or another value associated with scope email).

If you have set up your OAuth integration and implemented login on your frontend, users may be able to authenticate themselves. However, this alone is not sufficient for your frontend to communicate with VTEX REST APIs.

To enable this communication, your frontend application must exchange the access token from the OAuth login for a VTEX user token. This can be achieved through the POST Exchange OAuth access token for VTEX credential endpoint.

Check out request and response body examples below and refer to the POST Exchange OAuth access token for VTEX credential API reference for more details on each field.

Request body example

Response body example

Once with a valid VTEX user token, your frontend application can leverage VTEX APIs to manage various commerce capabilities of your store, including product information, shopping cart management, and checkout.

Learn more about machine authentication in VTEX and how to use user tokens to authenticate your requests.

Since your store is not using VTEX's native frontend to authenticate shoppers, there are some capabilities that your application must be prepared to handle:

• Managing login flow with the external identity provider.
• Making sure that the OAuth access token has scope email (or another value associated with scope email).
• Keeping the OAuth access token in the contexts where it is relevant.
• Refreshing tokens and other information when necessary.
• Keeping track of the expiration time set for the VTEX user token.
• Requiring new login if it was somehow revoked.
• Repeating the token exchange in case the shopper had to log in again.

See these other guides to learn more about building a headless shopping experience using VTEX:

• Headless commerce overview
• Headless catalog and search
• Headless cart and checkout
• Headless profile management and order history