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

  • Connect a custom template on any platform to an existing Wix project.
  • Change allowed redirect domains for an external client app or site.
  • Prevent an existing client app or site from connecting to a Wix project.

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

Setup

To use the OAuthApps API, install the @wix/auth-management package using npm or Yarn:

Copy
1
npm install @wix/auth-management

or

Copy
1
yarn add @wix/auth-management

Then import { oAuthApps } from @wix/auth-management:

Copy
1
import { oAuthApps } from '@wix/auth-management'
Was this helpful?
Yes
No
createOAuthApp( )
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.

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.

Note: The OAuth app secret is returned only when creating the OAuth app, and can't be retrieved later. Store the secret in a secure location.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage OAuth Apps
Learn more about permission scopes.
Copy
function createOAuthApp(oAuthApp: OAuthApp): Promise<OAuthApp>
Method Parameters
oAuthAppOAuthAppRequired
OAuth app to create.
Returns
Return Type:Promise<OAuthApp>
Was this helpful?
Yes
No
getOAuthApp( )
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.
Copy
function getOAuthApp(oAuthAppId: string): Promise<OAuthApp>
Method Parameters
oAuthAppIdstringRequired
ID of the OAuth app to retrieve.
Returns
Return Type:Promise<OAuthApp>
Was this helpful?
Yes
No
queryOAuthApps( )
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.
PROPERTYSUPPORTED FILTERS & SORTING
_ideq()
_createdDateascending(),descending()
nameascending(),descending()

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.
Copy
function queryOAuthApps(): OAuthAppsQueryBuilder
Request
This method does not take any parameters
Returns
Return Type:OAuthAppsQueryBuilder
Was this helpful?
Yes
No
updateOAuthApp( )
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 are updated.

You can update the following fields:

  • name
  • description
  • allowedDomain
  • loginUrl
  • logoutUrl

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage OAuth Apps
Learn more about permission scopes.
Copy
function updateOAuthApp(_id: string, oAuthApp: UpdateOAuthApp): Promise<OAuthApp>
Method Parameters
_idstringRequired
ID of the OAuth app.
oAuthAppUpdateOAuthAppRequired
Returns
Return Type:Promise<OAuthApp>
Was this helpful?
Yes
No