About the OAuth Apps API

The OAuth Apps API enables you to manage OAuth apps for a Wix Headless project or site. An OAuth app authorizes an external client app or site, on any platform, to authenticate with a Wix site or project and manage its data using the Wix JavaScript SDK.

With the OAuth Apps API, you can:

  • Create a new OAuth app to enable an external client to access a Wix project or site.
  • Query and retrieve information about existing OAuth apps.
  • Update details of an existing OAuth app.
  • Delete an OAuth app.

To use Wix Headless functionality you need to create an OAuth app, either using the OAuth Apps API or in the project or site's dashboard. For instructions on how to do this, see how to Set Up Authorization for Wix Headless.

Once you have created an OAuth app, learn how to Set Up the Wix JavaScript SDK for Wix Headless.

Before you begin

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

  • Each external client should authenticate using its own OAuth app.
  • You can only generate a secret once for each OAuth app, and the secret can't be retrieved later. Store the secret securely.
  • After you delete an OAuth app, an external client can no longer make API calls by authenticating with its client ID.

Use cases

Terminology

  • OAuth app: An intermediary application that authorizes and authenticates an external client to access data on a Wix project or site.
  • Project: A Wix business backend incorporating Wix business solutions, but which doesn't necessarily have a Wix site frontend.
  • Client: An external app or site, built on any platform, which accesses or manages data on a Wix project or site using Wix APIs.
  • Client ID: A unique ID that an external client uses to authenticate for making API calls.
  • Client secret: A unique credential that an external client uses to authenticate for admin access to a Wix project or site.
Was this helpful?
Yes
No

OAuth Apps: Sample Use Cases & 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.

Connect a custom template on any platform to an existing Wix project

You can create a frontend template, on an external platform, that takes advantage of business solutions on a Wix project.

For any external app or site to access a Wix project's data, it must be authorized in advance by creating an OAuth app. To enable project owners to connect a site or app built on your template to their existing Wix project data, follow these steps:

  1. Create a template on any platform and integrate API calls from the Wix JavaScript SDK to access and manage business solutions in a Wix project.
  2. Create a Wix app that a project owner can install.
  3. Make sure your app requests the Manage OAuth Apps permission scope.
  4. Obtain the domain name for the deployment of the site or app built on the template.
  5. In your app code, call Create OAuth App. Specify a name and optional description that identify the client clearly. In the allowedDomains array, provide the deployment domains from the previous step.
  6. Store the returned OAuth app's id securely.
  7. Assign the ID to a secure environment variable in the template code. The template can now access the Wix project's data.

Change allowed redirect domains for an external client app or site

Whenever an external client redirects a user to Wix for authentication, the client provides a URL for Wix to redirect the user back to after authentication. To ensure security, Wix only redirects the user if the domain has been approved in advance in the OAuth app's settings. To update an external client's approved URLs, follow these steps:

  1. Make sure you have the OAuth app ID for the external client.
  2. Obtain a complete list of domains to approve for the external site or app.
  3. Call Update OAuth App with the OAuth app ID as a path parameter. Pass all approved domains in the oAuthApp.allowedDomains body parameter, and pass ["allowedDomains"] in the mask.paths body parameter.
  4. The external app or site can now provide any redirect URL from the updated list.

Prevent an existing client app or site from connecting to a Wix project

To prevent a client site or app from accessing a Wix project's data, you can disable its permissions by deleting the OAuth app it connects through. To delete the OAuth app, follow these steps:

  1. Obtain the OAuth app ID used by the client app or site.
  2. Call Delete OAuth App with the OAuth app ID as a path parameter.
  3. The client app or site can no longer connect to the Wix project. If you wish to reactivate its connection in future, create a new OAuth app with Create OAuth App and update the OAuth app ID used in the client app or site code.
Was this helpful?
Yes
No

OAuth Apps: Supported Filters and Sorting

The following table shows field support for filters and sorting for the OAuthApp object:

FieldSupported FiltersSortable
id$eq
createdDateSortable
nameSortable

Related content: API Query Language, Query OAuth Apps endpoint

Was this helpful?
Yes
No

O Auth App Object

Attributes
idstringRead-onlyformat GUID
ID of the OAuth app.

createdDatestringRead-onlyformat date-time
Date and time the OAuth app was created, in ISO 8601 format.

namestringminLength 2maxLength 256
Display name of the OAuth app, as it appears in the dashboard.

descriptionstring
Description of the OAuth app, as it appears in the dashboard.

secretstringRead-only
For internal use only.

loginUrlstringformat WEB_URL
External login URL to which users are redirected automatically to authenticate. If no login URL is specified, the user is redirected to Wix to authenticate.

allowedRedirectUrisArray <string>format URImaxItems 10
List of URIs to which redirection from Wix is allowed after authentication. When a client redirects a user to Wix for authentication, the client provides a URI to redirect the user back to after the user has been authenticated. Wix only redirects the user if the exact URI is contained in this array.

allowedRedirectDomainsArray <string>maxItems 10
List of domains to which redirection from Wix is allowed after processes other than authentication. When a client redirects a user to a Wix page (for example, for checkout), the client provides a URL to redirect the user back to. Wix only redirects the user if the URL is in one of the specified domains.

allowSecretGenerationboolean
Whether a secret can be generated for this OAuth app. Default: true until a secret has been generated for the OAuth App.
Was this helpful?
Yes
No

PostCreate OAuth App

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a new OAuth app for a Wix Headless client.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage OAuth Apps
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/oauth-app/v1/oauth-apps

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetGet OAuth App

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves an OAuth app by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage OAuth Apps
Read OAuth Apps
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/oauth-app/v1/oauth-apps/{oAuthAppId}

Was this helpful?
Yes
No

PatchUpdate OAuth App

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates an OAuth app.

Only fields provided in mask.paths are updated.

You can update the following fields:

  • name
  • description
  • allowedDomain
  • loginUrl

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage OAuth Apps
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/oauth-app/v1/oauth-apps/{oAuthApp.id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery OAuth Apps

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of OAuth apps, given the provided paging, filtering, and sorting.

Query OAuth Apps runs with these defaults, which you can override:

  • Results are sorted by id in descending order.
  • paging.offset is 0.

For field support for filters and sorting, see OAuth Apps: Supported Filters and Sorting

To learn about working with Query endpoints in general, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage OAuth Apps
Read OAuth Apps
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/oauth-app/v1/oauth-apps/query

Was this helpful?
Yes
No

OAuth App Created

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an OAuth app is created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.headless.v1.o_auth_app.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

OAuth App Updated

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an OAuth app is updated.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.headless.v1.o_auth_app.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

OAuth App Deleted

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an OAuth app is deleted.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.headless.v1.o_auth_app.

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No