OAuth 2: Sample Use Cases and Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Make API calls with basic OAuth

Your app can make Wix API calls by using OAuth.

Prerequisites

Before your app can call Wix APIs, you need to set up OAuth.

1. Store your app’s secret key in a secure location. You can find it in your app’s OAuth settings page in the Wix Dev Center. Don’t share the key with anyone or make it public in any way.

2. Subscribe to the Instance App Installed webhook. This webhook is triggered every time a new user installs your app. Then, save the instanceId.

   Tip: You don’t need to subscribe to this webhook, if your app doesn’t need to call Wix APIs or manage a list of app installations. However, we highly recommend subscribing to the Instance App Installed webhook whenever you need a mapping to manage resources for every app instance.

3. 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 user input such as creating an account or configuring parameters in order for the app to become active. In case your app doesn’t require user input, 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"}.

The flow

To make API calls with OAuth:

1. Request a fresh access token by calling Create Access token. Pass your app ID, the app’s secret, and the relevant app instance ID in the raw HTTP request’s body field.
2. Extract the access token from the raw HTTP response's body. Keep in mind that the access token is valid for only 4 hours.
3. Use the access token as authorization header in the relevant API call.
4. Create a new access token after it expires.

Make API calls with advanced OAuth

Your app can make Wix API calls by using advanced OAuth.

Prerequisites

Before your app can call Wix APIs with advanced OAuth, you need to complete the following setup.

1. In the Wix Dev Center, under Build your app, navigate to OAuth.
2. Find your app’s secret key and store it 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.
7. 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 immediately forwarding new users to the authorization request that’s described in the next step.
8. Redirect the user back 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.
9. 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 query parameter. In case it doesn’t match the one provided by you, the request may have been created by a third party. Then, we recommend aborting the process.
10. 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. Note that the access token is only valid for 5 minutes. You need to request a new access token to make Wix API calls after it has expired.
11. 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.
12. 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.
13. 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 in order for the app to become active. In case 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"}.

The flow

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

To make API calls with advanced OAuth:

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. Keep in mind that the access token is only valid for 5 minutes.
3. Create a new access token after it has expired.