API Reference

Integration Guides
Login (SSO)
Unifying login for different accounts

Diverse ecommerce operations may require different account structures according to their business needs, such as different stores belonging to the same group. When using multiple accounts, you can unify customer login to reduce friction and provide a smoother shopping experience.

In this guide, you will learn how to unify login for different VTEX accounts. This method enables you to use the VTEX ID authentication of a given store to authenticate shoppers accessing other stores with OAuth 2.0.


To unify login for different accounts, you must choose one account that will be the primary account. This means it will be the OAuth identity provider. Other accounts will be able to use the primary account’s login by acting as the service provider in the OAuth flow of information. These are referred to as secondary accounts in this tutorial.

To implement this connection, you must:

Set up OAuth Provider in the primary account

To set up your OAuth Provider, follow these steps:

  1. Use the VTEX IO CLI to log in to your primary account by running the following command:

vtex login {accountName}

  1. Run this command to install the OAuth Provider app:

vtex install vtex.oauth-provider-admin

  1. On the Admin panel of your primary account, go to ACCOUNT SETTINGS > OAuth Provider. This will take you to the OAuth Provider app tab.

    {"base64":"  ","img":{"width":1355,"height":567,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":32660,"url":""}}


  3. Fill in the new OAuth client information, which is the secondary account.

    {"base64":"  ","img":{"width":981,"height":717,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":28473,"url":""}}

  • Name: this identifies the OAuth client. For instance, you may use the name of the corresponding secondary account.
  • Allowed URI’s:


  • Credential Type: Web Store.
  • Login URL:


  1. Click SAVE.
  2. Once you have saved your new OAuth client, you will be able to see it on the OAuth Provider Admin tab. Click on the client’s name to see its details.
    {"base64":"  ","img":{"width":1008,"height":318,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":17238,"url":""}}
  3. Copy the client ID and secret. You will need these credentials to set up the OAuth connection in the secondary account.

Set up OAuth connection in the secondary account

Now that you have set an OAuth identity provider in your primary account and registered your secondary account as an OAuth client, you must head to the Admin panel of your secondary account and set up the connection between the accounts according to the custom OAuth integration guide. For the purpose of this method, there is some custom OAuth configuration information that you must fill in specific ways. See the specification below to learn how to fill in this information for each configuration step of the custom OAuth integration guide.

The information below is meant for VTEX accounts using VTEX ID as identity providers. If you want to use a custom OAuth identity provider, see the custom OAuth integration guide.

1. Provider Details

Client ID keyclient_id
Client ID valueclient_secret

2. Authorization Code

Custom query string parameterresponse_type: code
Callback Request Information authorization code query string parameter keycode

The URL above requires your account host. Learn more about how to set your account host.

3. Access Token Exchange

Set Content-Typeapplication/x-www-form-urlencoded
Authorization code parameter keycode
Custom request query string parametergrant_type: authorization_code
Response access token parameter keyaccess_token
Response expires in parameter keyexpires_in

The URL above requires your account host. Learn more about how to set your account host.

4. Get User Info

Where to send Access Token - Send on query string toggleDisabled
Response User e-mail parameter keye-mail
Response User ID parameter keyuserId
Response User name parameter keyusername

The URL above requires your account host. Learn more about how to set your account host.

Account host

The account host, used in the URLs for some of the configuration steps above, can be defined in the VTEX Admin panel by going to ACCOUNT SETTINGS > Account management > Account.

{"base64":"  ","img":{"width":1366,"height":693,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":48714,"url":""}}

Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page