> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: AppStrategy

## Article: AppOAuthStrategy

## Article Link: https://dev.wix.com/docs/sdk/core-modules/sdk/app-strategy.md

## Article Content:

# AppStrategy

<blockquote>

__Note:__
This strategy is only intended for
[backend extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/about-backend-extensions.md).
For [frontend extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions.md#frontend-extensions),
use [host modules](https://dev.wix.com/docs/sdk/host-modules/about-host-modules.md)
instead.

</blockquote>

This strategy is used along with a [`Wix Client`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) to authenticate API calls made by Wix apps using OAuth tokens. The resulting access token is specific to a particular app instance. For more information, see [About OAuth](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/about-oauth.md).

Get the access token by using one of the following methods:

* Provide the specific app instance ID. For an example, see [Use OAuth](#use-oauth).
* Provide the refresh token of a specific app instance obtained during [custom authentication (legacy)](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/custom-authentication-legacy.md). This approach is based on the OAuth Authorization Code flow and requires storing a persistent mapping between instance IDs and refresh tokens in a database or similar storage solution. For an example, see [Custom authentication (legacy)](#custom-authentication-legacy).

When using this authentication strategy, the requester's identity is that of the corresponding Wix app. The permissions for the app are set in the Dev Center. To learn more about permissions, see [How to Add Permissions](https://dev.wix.com/docs/build-apps/develop-your-app/access/authorization/about-permissions.md).

## AppStrategy()

Creates an authentication strategy object that uses OAuth tokens for app authentication.

#### Syntax

```js
AppStrategy({appId: string, appSecret: string, publicKey?: string, instanceId?: string, refreshToken?: string}): AppStrategy
```

#### Parameters

| Name                             | Type   | Description                                                                                                                                                                                                                                       |
| :------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `appId`                          | string | The app ID. You can find this value in the Dev Center in the **OAuth** page.                                                                                                                                                                      |
| `appSecret`                      | string | The app secret. You can find this value in the Dev Center in the **OAuth** page.                                                                                                                                                                  |
| `publicKey`                      | string | **Optional.** The app public key in the case of using webhooks. [Find your app's public key](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/webhooks/handle-events-with-webhooks-for-self-hosting-using-the-java-script-sdk.md). |
| **One of:**                      |        |                                                                                                                                                                                                                                                   |
| <ul><li>`instanceId`</li></ul>   | string | **Optional.** A unique identifier for an instance of the app.                                                                                                                                                                                     |
| <ul><li>`refreshToken`</li></ul> | string | **Optional.** A token used to obtain new access tokens for a specific instance ID.                                                                                                                                                                |
| <ul><li>`accessToken`</li></ul>  | string | **Optional.** Access token for a specific instance ID.                                                                                                                                                                                            |

#### Returns

`AppStrategy`

## Methods

### getInstallUrl()

Retrieves the Wix app install URL.

Use this function to initiate the OAuth Authorization Code flow. When they user arrives at the install URL, they're prompted to approve the required permissions. Then, the user is redirected to the specified redirect URL with an authorization code.

#### Syntax

```js
getInstallUrl(redirectUrl: string): string
```

#### Parameters

| Name          | Type   | Description                                                  |
| :------------ | :----- | :----------------------------------------------------------- |
| `redirectUrl` | string | The URL to redirect the user to with the authorization code. |

#### Returns

A string representing the install URL.

### handleOAuthCallback()

Retrieves the access token, refresh token, and instance ID for authentication.

Use this function during the OAuth Authorization Code flow in the callback handler of your HTTP server.

#### Syntax

```js
handleOAuthCallback(url: string): string
```

#### Parameters

| Name  | Type   | Description                                                |
| :---- | :----- | :--------------------------------------------------------- |
| `url` | string | The URL containing the authorization code to be processed. |

#### Returns

`accessToken`, `refreshToken`, `instanceId`

### getTokenInfo()

Retrieves information about the `accessToken` that was passed to `AppStrategy` upon initialization.

<blockquote class="important">
  <strong>Important:</strong>
  
  If a `refreshToken` or `instanceId` was passed to `AppStrategy` upon initialization, rather than an `accessToken`, then this method throws an error.
</blockquote>


#### Syntax

```js
getTokenInfo(): Promise<tokenInfo>
```

#### Returns

`tokenInfo`

| Name          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active`      | boolean | Whether the token is active.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `subjectType` | string  | [Identity](https://dev.wix.com/docs/sdk/articles/getting-started/about-identities.md) of the subject. Supported values:<br/><ul><li>`APP`</li><li>`USER`</li><li>`MEMBER`</li><li>`VISITOR`</li><li>`UNKNOWN`</li></ul>                                                                                                                                                                                                                          |
| `subjectId`   | string  | ID of the subject to which the token is issued.                                                                                                                                                                                                                                                                                                                                                                                               |
| `exp`         | number  | Token expiration timestamp.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `iat`         | number  | Token issue timestamp.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `clientId`    | string  | ID of the app that created the token, as defined in the [Wix Dev Center](https://dev.wix.com/).                                                                                                                                                                                                                                                                                                                                               |
| `siteId`      | string  | ID of the site to which the token is issued.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `instanceId`  | string  | The [instance ID](https://dev.wix.com/docs/sdk/backend-modules/app-management/app-instances/introduction.md) of the app that the access token was created for. Subscribe to the [`onAppInstanceInstalled()`](https://dev.wix.com/docs/sdk/backend-modules/app-management/app-instances/on-app-instance-installed.md) webhook to receive a notification including the new app instance ID whenever a version of your app is installed on a Wix site. |

### elevated()

Returns an `AppStrategy` object with elevated permissions.

The `AppStrategy` object returned by `elevated()` provides [Wix App](https://dev.wix.com/docs/sdk/articles/getting-started/about-identities.md#wix-app) authentication. This means the client can call SDK functions using the app's permissions. Use `elevated()` when you're working with a client that has site visitor, site member, or Wix user authentication and you need make a call with app authentication. The `AppStrategy` object returned by `elevated()` loses its site visitor or site member identity.

Learn more about [elevated permissions](https://dev.wix.com/docs/sdk/articles/working-with-the-sdk/about-elevated-permissions.md).

#### Syntax

```js
elevated(): AppStrategy
```

#### Returns

`AppStrategy`

## Examples

In most cases, we recommend using the Client Credentials flow. The Authorization Code flow enables you to redirect the user to an external or custom URL during app installation, but it necessitates storing a persistent mapping between instance IDs and refresh tokens in a database or similar storage solution. If this functionality isn't needed, we suggest opting for the Client Credentials flow due to its simplicity and security.

### Use OAuth

The following example shows how to implement OAuth, which follows the OAuth Client Credentials protocol.

In this frontend code, the app instance ID is retrieved from the environment and used to create a Wix client with the `AppStrategy` bound to this ID. Then, when the client initiates an API request, an additional call is made behind the scenes to acquire an access token. This token is included in the request headers to enable an authenticated API call. In this case, a call is made to the products API.

```js
import { createClient, AppStrategy } from '@wix/sdk';
import { products } from '@wix/stores';

// Implement a function to get the instance ID of the relevant app.
// The implementation depends on the environment from which you're using the SDK.
const instanceId = getInstanceIdFromEnvironment();

// Create a Wix client bound to the instance ID.
// Find the app ID and secret in the OAuth page of the Dev Center.
// Find your public key in the Webhooks page of the Dev Center.
const myClient = createClient({
  auth: AppStrategy({
    appId: 'YOUR_APP_ID',
    appSecret: 'YOUR_APP_SECRET',
    publicKey: 'YOUR_APP_PUBLIC_KEY_IF_YOU_USE_WEBHOOKS',
    instanceId
  }),
  modules: {
    products,
  }
});

// Use the client with the `products` module to query products.
const { items } = await myClient.products.queryProducts()
  .startsWith('name', 'shoes')
  .limit(4)
  .find();
```

### Custom authentication (legacy)

<blockquote class="caution">

**Caution:** Custom authentication (legacy) is no longer available for new apps. This section is only relevant for existing apps that already use custom authentication.

</blockquote>

The following code example shows how to implement custom authentication, which follows the OAuth Authorization Code protocol.

In this backend code, the user is redirected to the install URL to acquire an authorization code. The user is prompted to approve the required permissions for installation. Then, the access token, refresh token, and instance ID are retrieved and stored for future use.

```js
import { createClient, AppStrategy } from '@wix/sdk';
import { products } from '@wix/stores';

const myClient = createClient({
  auth: AppStrategy({
    appId: 'YOUR_APP_ID',
    appSecret: 'YOUR_APP_SECRET',
    publicKey: 'YOUR_APP_PUBLIC_KEY_IF_YOU_USE_WEBHOOKS',
  }),
  modules: {
    products,
  }
});

// Implement a function to redirect the user to the install URL.
// Then, the user is sent to the redirect URI with an authorization code.
redirectUsingYourServer(myClient.auth.getInstallUrl({ redirectUrl: 'YOUR_REDIRECT_URL' }));

// In your redirect URL endpoint, get the access token, refresh token, and instance ID.
const { accessToken, refreshToken, instanceId } = await myClient.auth.handleOAuthCallback(request.url);

// Store the mapping between the instance ID and the refresh token in persistent storage.
await storeRefreshTokenInStorage(instanceId, refreshToken);
```

Then, in the frontend code, the stored refresh token is fetched from storage based on the instance ID and used to create a Wix client with the `AppStrategy` bound to this token. This configuration enables the client to make authenticated API calls.

```js
import { createClient, AppStrategy } from '@wix/sdk';
import { products } from '@wix/stores';

// Implement a function to get the instance ID of the relevant app.
// The implementation depends on the environment from which you're using the SDK.
const instanceId = getInstanceIdFromEnvironment();

// Implement a function to get the refresh token of the relevant app instance.
// The implementation will depend on the storage solution.
const refreshToken = await getRefreshTokenFromStorage(instanceId);

// Get a Wix client bound to the refresh token.
// Find the app ID and secret in the OAuth page of the Dev Center.
// Find your public key in the Webhooks page of the Dev Center.
const myClient = createClient({
  auth: AppStrategy({
    appId: 'YOUR_APP_ID',
    appSecret: 'YOUR_APP_SECRET',
    publicKey: 'YOUR_APP_PUBLIC_KEY_IF_YOU_USE_WEBHOOKS',
    refreshToken
  }),
  modules: {
    products,
  }
});

// Use the client with the `products` module to query products.
const { items } = await myClient.products.queryProducts()
  .startsWith('name', 'shoes')
  .limit(4)
  .find();
```