About the OAuth 2 API

The OAuth 2 API allows your app to manage tokens that you can use to authenticate Wix API calls. By default, OAuth authentication follows the OAuth Client Credentials protocol. In most cases, it's sufficient that your app uses this basic OAuth. Wix also offers advanced OAuth settings in case you need to identify your customers along the installation process, or if you need to redirect them at the end of the process before they see your app's dashboard.

With the OAuth 2 API, you can:

Learn more about:

Before you begin

It's important to note the following points before starting to code:

  • If your app uses advanced OAuth, Wix sends you an authorization code while redirecting new users to your app URL. You must use this authorization code within 10 minutes to create a refresh token by calling Request an access token. If the process fails, you're unable to retrieve access tokens with Refresh an Access Token. Though from the site owner's point-of-view, it seems that the app installation has succeeded. You have 2 options in this situation: Ask the site owners to re-install your app, or fall back to retrieving access tokens with the basic OAuth strategy by calling Create Access Token.
  • If your app uses basic OAuth to authenticate Wix API calls, you must create access tokens by calling Create Access Token.

Use cases

Terminology

  • OAuth: Authorization framework used by Wix that enables 3rd-party apps to obtain limited access to Wix APIs. In Wix, OAuth is sometimes also called basic OAuth to differentiate it from advanced OAuth.
  • Advanced OAuth: Advanced version of the OAuth protocol that's used by Wix. Wix recommends that your app uses advanced OAuth only if you need to redirect your users to a URL that's outside the Wix ecosystem during the app installation flow.
  • Authorization code: String that Wix sends to your app during the advanced OAuth flow, after a new user has finished the installation process and granted your app the requested permissions. It has an expiration time of 10 minutes. You must create your app's refresh token before the authorization code expires.
  • Refresh token: String that your app can use to generate access tokens in the advanced OAuth flow. It never expires. Store the refresh token in a secure location. Don't share it with anyone or make it public in any way.
  • Access token: String that you can use in the authorization header to make Wix API calls. All Wix OAuth access tokens are of type "Bearer". Learn more about access token types.
Was this helpful?
Yes
No

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.
Was this helpful?
Yes
No

PostRequest an Access Token

Creates your app’s refresh token and an initial access token.

Important: This endpoint is relevant for advanced OAuth only. It isn’t relevant for basic OAuth.

Wix sends your app the authorization code after a new user has completed the installation process and given your app permission to access their data.

You must pass the authorization code, your app ID, your app’s secret key, and {“grantType”: “authorization_code”} to create the refresh token and an initial access token.

Endpoint
POST
https://www.wixapis.com/oauth/access

Was this helpful?
Yes
No

PostRefresh an Access Token

Creates a new access token.

Important: This endpoint is relevant for advanced OAuth only. When authorizing with basic OAuth use Create Access Token instead.

You must pass your app ID, your app’s secret key, the refresh token, and {“grantType”: “refresh_token”} to create a new access token.

Endpoint
POST
https://www.wixapis.com/oauth/access/

Was this helpful?
Yes
No

PostCreate Access Token

Creates an access token.

Important: This endpoint is relevant for basic OAuth only. When authorizing with advanced OAuth use Refresh an Access Token instead.

The endpoint accepts raw HTTP requests. You must pass the request's body parameters formatted as bytes in the raw HTTP request's body field, following this template: {"grantType": "client_credentials", "client_id": "<APP_ID>", "client_secret": "<APP_SECRET_KEY>", "instance_id": "<INSTANCE_ID>"}.

When the call succeeds, Wix returns {"statusCode": 200} and the created access token in the body field of the raw HTTP response.

In case the call fails, Wix returns the relevant 4XX error code in the raw HTTP response's statusCode field and details about the error in body. Error details follow the conventions of the Internet Engineering Task Force (IETF).

Endpoint
POST
https://www.wixapis.com/oauth2/token

Was this helpful?
Yes
No