Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# 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](https://oauth.net/2/grant-types/client-credentials/). 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](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/create-access-token) for basic OAuth.
+ [Create a refresh token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/request-an-access-token) for advanced OAuth.
+ [Create access tokens](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/refresh-an-access-token) for advanced OAuth.

Learn more about:
+ [Basic and advanced OAuth](https://dev.wix.com/docs/build-apps/build-your-app/authentication/about-oauth).
+ [How to set up and use basic OAuth](https://dev.wix.com/docs/build-apps/build-your-app/authentication/use-oauth).
+ [How to set up and use advanced OAuth](https://dev.wix.com/docs/build-apps/build-your-app/authentication/use-advanced-oauth).

## 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](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/request-an-access-token). If the process fails, you're unable to retrieve access tokens with [Refresh an Access Token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/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](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/create-access-token).
+ If your app uses basic OAuth to authenticate Wix API calls,
   you must create access tokens by calling
   [Create Access Token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/create-access-token).

## Use cases

+ [Make API calls with basic OAuth](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/sample-flows#make-api-calls-with-basic-oauth)
+ [Make API calls with advanced OAuth](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/sample-flows#make-api-calls-with-advanced-oauth)

## 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](https://oauth.net/2/access-tokens/).

# 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](https://dev.wix.com/).
   Don’t share the key with anyone or make it public in any way.
1. Subscribe to the
   [Instance App Installed webhook](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed).
   This webhook is triggered every time a new user installs your app. Then, save the `instanceId`.
   <blockquote class="tip">

   __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.
   </blockquote>
1. 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](https://dev.wix.com/docs/rest/api-reference/app-management/apps/bi-event/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](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/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.
1. Extract the access token from the raw HTTP response's `body`. Keep in mind
   that the access token is valid for only 4 hours.
1. Use the access token as authorization header in the relevant API call.
1. [Create a new access token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/create-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](https://dev.wix.com/), under __Build your app,__ navigate to __OAuth__.
1. Find your app’s __secret key__ and store it securely. Don’t share it with anyone or make it public in any way.
1.  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.
1.  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.
1. Make sure to click __Save__ before navigating away from the OAuth settings page.
1. Confirm that the [Cross-Origin-Opener-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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`.
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 immediately forwarding new users to the authorization request that’s described in the next step.
1. Redirect the user back to Wix at `https://www.wix.com/installer/install`. There, they’re asked to approve the complete list of [permissions](https://dev.wix.com/docs/build-apps/build-your-app/authentication/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.
1. 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.
1. 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](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/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.
1. 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.
1. Optional: If your app includes a [dashboard page](https://dev.wix.com/docs/build-apps/developer-tools/extensions/dashboard-page) or [dashboard extension](https://dev.wix.com/docs/build-apps/developer-tools/extensions/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.
1.  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](https://dev.wix.com/docs/rest/api-reference/app-management/apps/bi-event/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](https://dev.wix.com/api/rest/app-management).

To make API calls with advanced OAuth:

1. Request a new access token by calling [Refresh an Access Token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/refresh-an-access-token). Pass `{"grant_type": "refresh_token"}` and your app’s secret key as `client_secret` in the request.
1. 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.
1. [Create a new access token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/create-access-token)
   after it has expired.


Once a user has completed the installation process and given your app permission to access their data, use the 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 5 minutes.) You can find your secret key in the Wix Developers Center.

The App ID as defined in the Wix Developers Center

client_id

The Secret Key for your app as defined in your Wix Developers Center

client_secret

code

Value must be set to "authorization_code"

grant_type

Request Access Token Response

Created access token. Always starts with `"OauthNG.JWS"`

access_token

Create Access Token Response

Created access token that you can use to make Wix API calls. It expires after 5 minutes.

Your app instance’s refresh token that never expires. Identical to the one that you’ve sent in the request.

refresh_token

ID of the account that [created](https://dev.wix.com/docs/rest/app-management/oauth-2/create-access-token) the token, as defined in the [Wix Dev Center](https://dev.wix.com/apps/my-apps).

accountId

active

ID of the app that [created](https://dev.wix.com/docs/rest/app-management/oauth-2/create-access-token) the token, as defined in the [Wix Dev Center](https://dev.wix.com).

clientId

The [instance ID](https://dev.wix.com/docs/rest/app-management/app-instance/introduction) of the app that the access token was created for. Subscribe to the [Instance App Installed](https://dev.wix.com/docs/rest/app-management/app-instance/app-instance-installed) webhook to receive a notification including the new app instance ID whenever a version of your app is installed on a Wix site.

instanceId

ID of the site to which the token is issued.

siteId

ID of the subject to which the token is issued.

subjectId

Type of subject to which the token is issued.

subjectType

Token Info Response

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


<blockquote class="important">

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

</blockquote>

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.


Create an advanced OAuth refresh and access token.

Request an Access Token

Creates a new access token.


<blockquote class="important">

__Important:__
This endpoint is relevant for advanced OAuth only. When authorizing with basic OAuth use [Create Access Token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/create-access-token) instead.

</blockquote>

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


Create an advanced OAuth access token.

Refresh an Access Token

 Creates an access token.


<blockquote class="important">

__Important:__
This endpoint is relevant for basic OAuth only. When authorizing with advanced OAuth use [Refresh an Access Token](https://dev.wix.com/docs/rest/api-reference/authorization/oauth-2/refresh-an-access-token) instead.

</blockquote>

 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)](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.7).


Create an OAuth access token.

Create an Access Token

Retrieves information about a specific access token. 


 Access tokens are specific to a subject and a client. A client (app) creates and issues an access token to a subject. The client may request a valid token from a subject to perform a certain action, such as an API call. 


 This endpoint works with both basic and advanced OAuth tokens.