Migration Rest Portal

Build Apps

Go Headless

Client

API Preview

Develop Websites

REST

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

or

```console
yarn add @wix/auth-management
```

Then import `authManagement` from `@wix/auth-management`:

```js
import authManagement from '@wix/auth-management'
```
  

auth-management

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.

createOAuthApp

getOAuthApp

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`.


|PROPERTY	|SUPPORTED FILTERS & SORTING	
|:---:|:---:|
|`_id`|[`eq()`](/o-auth-apps/o-auth-apps-query-builder/eq)|
|`_createdDate`|[`ascending()`](/o-auth-apps/o-auth-apps-query-builder/ascending),[`descending()`](/o-auth-apps/o-auth-apps-query-builder/descending)|
|`name`|[`ascending()`](/o-auth-apps/o-auth-apps-query-builder/ascending),[`descending()`](/o-auth-apps/o-auth-apps-query-builder/descending)|

queryOAuthApps

OAuthAppsQueryBuilder

Updates an OAuth app.


Only fields provided in `mask` are updated.

You can update the following fields:
+ `name`
+ `description`
+ `allowedDomain`
+ `loginUrl`

updateOAuthApp

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

or

```console
yarn add @wix/auth-management
```

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

```js
import { oAuthApps } from '@wix/auth-management'
```
  

---
title: Introduction
---

# About the OAuth Apps API

The OAuth Apps API enables you to manage OAuth apps for a [Wix Headless](https://dev.wix.com/api/sdk/about-wix-headless/overview) 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](https://dev.wix.com/api/sdk/introduction/about-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](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Foauth-apps-settings). For instructions on how to do this, see how to [Set Up Authorization](https://dev.wix.com/api/sdk/sdk-setup:-wix-headless/authorization) for Wix Headless.

Once you have created an OAuth app, learn how to [Set Up the Wix JavaScript SDK for Wix Headless](https://dev.wix.com/api/sdk/sdk-setup:-wix-headless/set-up-the-wix-sdk).

## 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.


OAuthAppsQueryResult

OAuthApps

OAuthApp

Date and time the OAuth app was created, in ISO 8601 format.

_createdDate

string

Whether a secret can be generated for this OAuth app.

Default: `true` until a secret has been generated for the OAuth App.

allowSecretGeneration

boolean

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.

allowedRedirectDomains

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.

allowedRedirectUris

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

description

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.

loginUrl

Display name of the OAuth app, as it appears in the dashboard.

name

secret

Adds a sort to a query, sorting by the specified properties in ascending order.

The `ascending()` function refines a `OAuthAppsQueryBuilder` to sort by the value of `propertyName` in ascending order.
You can specify multiple properties for sorting in ascending order by passing each property name as an additional argument. `ascending()` sorts the results in the order the properties are passed.
You can sort the following types:
- Number: Sorts numerically.
- Date: Sorts by date and time.
- String: Sorts lexicographically, so `'abc'` comes after `'XYZ'`.
If a property contains a number stored as a string (for example, `'0'`), that value is sorted alphabetically and not numerically. If a property doesn't have a value, that value is ranked lowest.

ascending

Adds a sort to a query, sorting by the specified properties in descending order.

The `descending()` function refines a `OAuthAppsQueryBuilder` to sort by the value of `propertyName` in descending order.
You can specify multiple properties for sorting in descending order by passing each property name as an additional argument. `descending()` sorts the results in the order the properties are passed.
You can sort the following types:
- Number: Sorts numerically.
- Date: Sorts by date and time.
- String: Sorts lexicographically, so `'abc'` comes after `'XYZ'`.
If a property contains a number stored as a string (for example, `'0'`), that value is sorted alphabetically and not numerically. If a property doesn't have a value, that value is ranked lowest.

descending

Refines a query to match items where the specified property equals the specified value.

The `eq()` function refines a `OAuthAppsQueryBuilder` to match only items where the value of the specified `propertyName` equals the specified `value`.
`eq()` matches only values of the same type. For example, `0` stored as a number doesn't match `'0'` stored as a string.
Matching strings with `eq()` is case-sensitive, so `'text'` isn't equal to `'Text'`.

Returns the query results.

The `find()` function returns a Promise that resolves to the query results and metadata.
The Promise is rejected if `find()` is called with insufficient permissions or if any of the previous functions used to refine the query are invalid.

find

Limits the number of items the query returns.

The `limit()` function defines the number of results a query returns in each page. Only one page of results is retrieved at a time.
You can use the `next()` and `prev()` functions to navigate the pages of a query result.

limit

Sets the number of items to skip before returning query results.

The `skip()` function defines the number of results to skip before returning new query results.
For example, if you query a collection and 50 items match your query, but you set `skip()` to `10`, the first 10 items that match are ignored, and the 11th through 50th items are returned.

skip

Indicates whether the query has more results.

You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.

hasNext

Indicates whether the query has previous results.

You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.

hasPrev

Retrieves the next page of query results.

The `next()` function retrieves the next page of query results.
The page size is defined by the [`limit()`](auth-management.OAuthApps.OAuthAppsQueryBuilder#limit) function and can be retrieved using the [`pageSize`](#pagesize) property. You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.
If items are added or removed between calls to `next()`, the values returned by `OAuthAppsQueryBuilder` may change.

Retrieves the previous page of query results.

The `prev()` function retrieves the previous page of query results.
The page size is defined by the [`limit()`](auth-management.OAuthApps.OAuthAppsQueryBuilder#limit) function and can be retrieved using the [`pageSize`](#pagesize) property. You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.
If items are added or removed between calls to `prev()`, the values returned may change.

Returns the index of the current page of results.

`currentPage` is a zero-based index of the current page of results, meaning the 1st page is `0`, the 2nd page is `1`, and so on.
If no results match the query, `currentPage` is undefined.
The page size is defined by the [`limit()`](auth-management.OAuthApps.OAuthAppsQueryBuilder#limit) function and can be retrieved using the [`pageSize`](#pagesize) property. You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.

currentPage

number

Returns an array of `oAuthApps` items that match the query.

`items` contains the current page of results retrieved by the query.
If no results match the query, `items` is an empty array.
The page size is defined by the [`limit()`](auth-management.OAuthApps.OAuthAppsQueryBuilder#limit) function and can be retrieved using the [`pageSize`](#pagesize) property. You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.

items

Returns the number of items in the current page of results.

`length` returns just the number of items in the current page, not the total number of items that match the query. For the total number of items that match the query, see [`totalCount`](#totalcount).
The page size is defined by the [`limit()`](auth-management.OAuthApps.OAuthAppsQueryBuilder#limit) function and can be retrieved using the [`pageSize`](#pagesize) property. You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.

length

Returns the requested page size.

`pageSize` returns the page size set in [`limit()`](auth-management.OAuthApps.OAuthAppsQueryBuilder#limit) in `OAuthAppsQueryBuilder`.

pageSize

Returns the `OAuthAppsQueryBuilder` object used to get the current results.

Use `query` to create and run a new query by chaining additional `OAuthAppsQueryBuilder` functions to it. You can filter only on properties that haven't already been used in the previous `OAuthAppsQueryBuilder`.

query

Returns the total number of items that match the query.

`totalCount` returns the total number of items that match the query, not just the number of items in the current page. For the number of items in the current page, see [`length`](#length).

totalCount

Returns the total number of pages the query produced.

The page size is defined by the [`limit()`](auth-management.OAuthApps.OAuthAppsQueryBuilder#limit) function and can be retrieved using the [`pageSize`](#pagesize) property. You can use the [`next()`](#next) and [`prev()`](#prev) functions returned by `oAuthApps` to navigate the pages of a query result.