Search.../
  1. Home
  2. Getting Started
  3. Overview
Generate a test token to explore our APIs

Getting Started

Authentication

When a site owner installs your app, they will grant you permission to collect their site data during the installation flow, which is based on the settings you provide in the Wix Developers Center. You will then receive an authorization code which you will use to request an access token and a refresh token. Then you’ll pass the access token as an authorization header in the API call.

Note:
Access and refresh tokens are user-specific. Access tokens are valid for 10 minutes. Refresh tokens are valid as long as the app is installed on the user's site.

Note: In certain installation flows, Wix will load your app and redirect URLs in an iframe. Make sure your content can be loaded on an iframe. For example, make sure you don't send the header 'X-FRAME-OPTIONS'

The OAuth Flow

We use OAuth 2.0 to authorize you to access our APIs and receive webhooks.

Note:
You’ll need to set up OAuth, Permissions, and Webhooks settings in the Wix Developers Center.

oauth flow diagram

Step 1: User Installs Your App

If the user chooses to install your app from within the Wix App Market, we redirect users to the App URL you defined in the Wix Developers Center. We include a token query parameter when we direct users to your App URL (we use it to keep track of the user as they go through the OAuth flow).

Note:
This redirect to the App URL is a back-end process only. The user shouldn't have to log in or sign up here - send them straight to the authorization request step described next.

Important:
If the user installs your app from your own platform, skip this step and go straight to step 2.

Step 2: App Sends Users to Authorize the App

Your app should redirect users to the URL below so that we can ask them to approve a list of permissions your app is requesting (based on the permissions you added in the Wix Developers Center).


Redirect users to the following URL:
https://www.wix.com/app-oauth-installation/consent


Send the following query parameters with the URL above:

  • token (required during installation from Wix only): The token you received as a query parameter to the App URL. We use it to keep track of users as they go through the OAuth flow.
  • appId: Your App ID, as defined in the Wix Developers Center.
  • redirectUrl: One of the redirect URLs you defined in the Wix Developers Center. You may define a separate redirect URL for each workflow (e.g., from the App Market and from your platform).
  • state (optional): You can add a unique string to identify users that were authenticated in the previous step. This is how you'll identify the user when we send them to your redirect URL.

    Important:
    Every redirect URL your app might use must be defined in the Wix Developers Center in advance.

Step 2a: User Authorizes the App

When the user approves the permissions your app has requested, Wix will continue to the next step.

Step 3: Wix Redirects the User to App Server With an Authorization Code

Wix will redirect the user back to your specified redirectUrl along the following query parameters:

  • code - A temporary authorization code. You’ll need this later, to request an access token to use our API.
  • state - The same value in case you provided one in the previous step. If the states don't match, the request may have been created by a third party and you should abort the process.
  • instanceId - The unique ID created for your app installation in the user specific site. All of your app’s components in the site share the same instance ID. Your app should always identify users using the instance ID.

Important:
If your app requires user login or signup - do so here.

Note:
After this step, the user is done. However, your app still has some work to do.

Step 4: App Submits the Authorization Code

Once the user completes the installation process and gives your app permission to access their data, use the temporary authorization code we sent you, together with your secret key, to request an access token and a refresh token. (The access token is only valid for 10 minutes.)

You can find your secret key in the Wix Developers Center.

Important:
This request must be a secure, server-to-server request.

Exchange the temporary authorization code for an access token using the OAuth > Access Token Request API method:

curl -X POST \
https://www.wix.com/oauth/access \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "authorization_code",
"client_id": <APP_ID>,
"client_secret": <APP_SECRET>,
"code": <AUTH_CODE>
}
Copy Code

Step 5: App Receives Access and Refresh Tokens

Wix will respond to your request in step 4 with a JSON response containing an access token and a refresh token (These tokens are not relevant for webhooks):

{
"refresh_token": <REFRESH_TOKEN>,
"access_token": <FRESH_ACCESS_TOKEN>
}
Copy Code

Note:
Request a new access token every time you call an API. Access tokens expire after 10 minutes. Use your refresh token to request a new access token.

Step 5a: App Completes the OAuth Flow

A. If the user's flow is finished, redirect them to the following endpoint to complete the OAuth flow and close the installation window/tab:

curl -X GET \
'https://www.wix.com/_api/site-apps/v1/site-apps/token-received?<ACCESS_TOKEN>' \
Copy Code

B. If the user can continue using your app, call the following endpoint to let us know that the flow is complete (without taking any visible action):

curl -X POST \
'https://www.wix.com/_api/site-apps/v1/site-apps/token-received' \
-H 'Authorization: <AUTH>'
Copy Code

Note:
Until one of these endpoints is called, the app will be marked as "pending installation" in Wix's database.

Step 6: App Requests Protected Data

Follow our API Reference section to request the user's protected data, with a fresh access token as the authorization header.

Was this helpful?