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

id
string
READ ONLY
format GUID
.
ID of the OAuth app.

createdDate
string
READ ONLY
format date-time
.
Date and time the OAuth app was created, in ISO 8601 format.

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

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

secret
string
READ ONLY
For internal use only.

loginUrl
string
format 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.

allowedRedirectUris
Array <string>
format URI
,
maxItems 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.

allowedRedirectDomains
Array <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.

allowSecretGeneration
boolean
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

post

Create 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.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/oauth-app/v1/oauth-apps

Event Triggers

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

get

Get 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.Authorization header required - pass the OAuth Access Token

Syntax

GET
https://www.wixapis.com/oauth-app/v1/oauth-apps/{oAuthAppId}

Was this helpful?
Yes
No

patch

Update 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.Authorization header required - pass the OAuth Access Token

Syntax

PATCH
https://www.wixapis.com/oauth-app/v1/oauth-apps/{oAuthApp.id}

Event Triggers

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

post

Query 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.Authorization header required - pass the OAuth Access Token

Syntax

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 Body

Event 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

id
string
Unique event ID. Allows clients to ignore duplicate webhooks.

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

slug
string
Event name. Expected
created
.

entityId
string
ID of the entity associated with the event.

eventTime
string
format date-time
.
Event timestamp.

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

originatedFrom
string
If present, indicates the action that triggered the event.

createdEvent
object
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 Body

Event 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

id
string
Unique event ID. Allows clients to ignore duplicate webhooks.

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

slug
string
Event name. Expected
updated
.

entityId
string
ID of the entity associated with the event.

eventTime
string
format date-time
.
Event timestamp.

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

originatedFrom
string
If present, indicates the action that triggered the event.

updatedEvent
object
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 Body

Event 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

id
string
Unique event ID. Allows clients to ignore duplicate webhooks.

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

slug
string
Event name. Expected
deleted
.

entityId
string
ID of the entity associated with the event.

eventTime
string
format date-time
.
Event timestamp.

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

originatedFrom
string
If present, indicates the action that triggered the event.

deletedEvent
struct
Event information.
Was this helpful?
Yes
No