Use Advanced OAuth Settings for Authenticating Your App

Advanced OAuth follows the industry-standard OAuth 2.0 protocol, which provides a secure way for site owners to grant your app permissions. Whenever a site owner installs your app, your app’s code must complete an OAuth handshake.

Before you start, it's important to understand how the Advanced OAuth flow works. The diagram below shows the complete flow including all actions that your app, Wix, and the user must take.

Step 1 | Set up advanced OAuth in the Wix DevCenter

Before setting up your app’s advanced OAuth settings, complete the OAuth settings in the Dev Center.

1. Under Build your app, navigate to OAuth.
2. Find your app’s secret key and store securely. Don’t share it with anyone or make it public in any way.
3. Enter an App URL. Wix redirects your new users to this URL when they install your app. You must use an HTTPS URL. During your app’s development, you may use localhost or ngrok URLs, but you need to change the URL before submitting your app for review.
4. Enter a Redirect URL. When a new user agrees to give your app the requested permissions, Wix redirects them to this URL. The redirect includes your app’s temporary authorization code.
5. Make sure to click Save before navigating away from the OAuth settings page.
6. Confirm that the Cross-Origin-Opener-Policy of both the app URL and redirect URL is set to unsafe-none. This enables Wix to close the redirect window as part of the flow. If the COOP of either URL has a different value, set it to unsafe-none.

Step 2 | Set up advanced OAuth in your app

1. When a new user installs your app, Wix redirects them to your app URL. Make sure to save the token query parameter value. We recommend that, at this point, you omit a sign-up or log-in step on your end. Instead, we recommend that you immediately forward your new user to the authorization request that’s described in the next step.
2. Redirect the user to Wix at https://www.wix.com/installer/install. There, they’re asked to approve the complete list of permissions that your app is requesting. Include the token, your appId, and redirectUrl as query parameters. You may also pass a state to identify your customers along the installation process.
3. Once the user approves the permissions for your app, Wix redirects them back to your app’s redirectURL. From the redirect’s query parameters, save the code and instanceId. Wix also includes state as a query parameter value. If the value doesn’t match the one provided by you, the request may have been created by a third party. Then, we recommend aborting the process.
4. This temporary authorization code is valid for 10 minutes. Use it to request your app’s refresh and access token by calling Request an Access Token. The access token is only valid for 5 minutes. You need to request a new access token to make Wix API calls after it expires.
5. Optional: If your app requires user login or sign-up, you can present the relevant modal to the user. Note that you can't do this prior to this point, but may choose to do at any later point.
6. Optional: If your app includes a dashboard page or dashboard extension that opens inside of Wix as an iframe, or another internal component of your app, your app needs to close the user’s browser window that has displayed the permission consent agreement. To close the consent window, redirect the user to this URL: https://www.wix.com/installer/close-window?access_token=<ACCESS_TOKEN>. Make sure to replace <ACCESS_TOKEN> with your app instance’s access token.
7. Optional: Update Wix about the status of your new app instance. At this point, your app instance’s state is“Setup Incomplete”. This state is useful if your app requires users to create an account or set other configuration parameters for the app to become active. If your app doesn’t require user input to become active, or after the user has completed their part, update your app instance’s state by calling Send BI Event. Make sure to pass {"eventName": "APP_FINISHED_CONFIGURATION"}.

Step 3 | Make API calls with advanced OAuth

After you successfully set up advanced OAuth, you can call the relevant Wix APIs described in our API Reference.

1. Request a new access token by calling Refresh an Access token. Pass {"grant_type": "refresh_token"} and your app’s secret key as client_secret in the request.
2. Use the returned access token as authorization header in the relevant API call. The access token is only valid for 5 minutes. Request a fresh one if it expires.
3. Use the access token as an authorization header in the relevant API call.
4. Create a new access token if it expired.