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:
- Create access tokens for basic OAuth.
- Create a refresh token for advanced OAuth.
- Create access tokens for advanced OAuth.
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.
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.
-
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.
-
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.
-
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:
- 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. - Extract the access token from the raw HTTP response's
body
. Keep in mind that the access token is valid for only 4 hours. - Use the access token as authorization header in the relevant API call.
- 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.
- In the Wix Dev Center, under Build your app, navigate to OAuth.
- Find your app’s secret key and store it securely. Don’t share it with anyone or make it public in any way.
- 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.
- 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.
- Make sure to click Save before navigating away from the OAuth settings page.
- 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 tounsafe-none
. - 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. - 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 thetoken
, yourappId
, andredirectUrl
as query parameters. You may also pass astate
to identify your customers along the installation process. - 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 thecode
andinstanceId
. Wix also includesstate
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. - 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. - 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.
- 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. - 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:
- Request a new access token by calling Refresh an Access Token. Pass
{"grant_type": "refresh_token"}
and your app’s secret key asclient_secret
in the request. - 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.
- Create a new access token after it has expired.
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.
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.
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).