The refresh token flow is a security mechanism in authentication systems that allows clients to obtain new access tokens without requiring users to reauthenticate.

This guide explains how to implement the refresh token flow in headless scenarios using native VTEX Login.

The refresh token flow operates with two types of tokens:

• Access token (VtexIdclientAutCookie_{{accountName}}): Short-lived token (24h), the primary credential used to authenticate API requests. It has a short expiration time to minimize security risks.
• Refresh token (vid_rt): Token with configurable expiration, always with a longer duration when compared to the access token (1, 7, or 30 days). Used to renew access tokens.

Contact VTEX Support to request the refresh token activation and expiration time configuration.

When the access token expires, but the refresh token is still valid, the client must use the refresh token to request a new access token via a dedicated renewal endpoint. The refresh process also returns a new refresh token, which replaces the previous one.

The following diagram illustrates the complete refresh token lifecycle, showing how authentication and token renewal work over time.

The following steps detail the refresh token flow shown in the diagram:

1. Login

   The user initiates authentication by logging into the system. VTEX ID processes the login request.

2. VTEX ID responds with tokens

   If authentication is successful, VTEX ID issues:

   • Access token
   • Refresh token

   These tokens are stored in cookies during the user's browser session.

3. Reauthentication after access token expiration

   After 24 hours, the access token expires. If the refresh token is still valid, the client can automatically obtain a new access token without any additional interaction.

   For example, if the refresh token has a 30-day lifespan and the user attempts to log in 29 days after their last authentication, the user’s browser sends the refresh token to VTEX ID to obtain a new access token. However, once the 30-day period ends, the refresh token expires, and the user must log in again to generate new access and refresh tokens.

   This happens automatically when stores use Store Framework or Legacy CMS Portal. For headless stores, it needs to be manually implemented following the instructions on this guide.

4. VTEX ID issues new tokens

   VTEX ID validates the refresh token and, if it's still valid:

   • Issues a new access token
   • Provides a new refresh token

   These new tokens replace the old ones in the browser.

This cycle repeats until the refresh token expires, ensuring uninterrupted user authentication.

To implement the refresh token flow in headless stores, use the VTEX ID API endpoints described in the following sections.

Initiate the authentication flow and obtain an authenticationToken by sending a GET request to the Start authentication endpoint.

Request:

Response body example:

After starting the authentication process, the next step is to proceed with the login method configured for the store. VTEX ID supports multiple login providers, including:

• Access key (login code sent by email)
• Email and password
• Social logins (Google, Facebook)
• Custom OAuth providers

Each store can enable one or more of these options, and all of which follow the same general flow at this stage: the client uses the authenticationToken from the previous step to complete the login process.

If the store uses access key as the login method, you must send a login code to the user's email using a POST request to the Send access key endpoint.

Example request for access key login:

The expected response is an empty 200 OK, and the user will instantly receive an email with the access code.

Once the user has provided their credentials or login code — depending on the login provider configured for the store — you must validate the session to complete authentication and receive the access and refresh tokens.

For the access key method, use the received access key and the user email to validate the session via a POST request to the Validate session endpoint. The request is structured as follows:

Request:

Response body example:

The response headers will set a vid_rt cookie, which contains the refresh token value, as illustrated below:

Finally, use the obtained refresh token to request a new access token via a POST request to the Refresh token endpoint.

Request:

Response body example:

The response cookies provide valid values for:

• vid_rt
• VtexIdclientAutCookie_{{accountId}}
• VtexIdclientAutCookie_{{accountName}}