In This Article

AppStrategy

Warning: This strategy is only intended for use with Wix app backend interfaces.

This strategy is used along with a Wix Client 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.

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

Provide the specific app instance ID. For an example, see Use OAuth.
Provide the refresh token of a specific app instance obtained during the Advanced OAuth flow. 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 Use Advanced OAuth.

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.

AppStrategy()

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

Syntax

Copy

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.
One of:
`instanceId`	string	Optional. A unique identifier for an instance of the app.
`refreshToken`	string	Optional. A token used to obtain new access tokens for a specific instance ID.
`accessToken`	string	Optional. Access token for a specific instance ID.

Returns

AppStrategy

Functions

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

Copy

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

Copy

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.

Important:

If a refreshToken or instanceId was passed to AppStrategy upon initialization, rather than an accessToken, then this method throws an error.

Syntax

Copy

Returns

tokenInfo

Name	Type	Description
`active`	boolean	Whether the token is active.
`subjectType`	string	Identity of the subject. Supported values: `APP` `USER` `MEMBER` `VISITOR` `UNKNOWN`
`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.
`siteId`	string	ID of the site to which the token is issued.
`instanceId`	string	The instance ID of the app that the access token was created for. Subscribe to the `onAppInstanceInstalled()` 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 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.

Syntax

Copy

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

Copy

Use Advanced OAuth

The following code example shows how to implement Advanced OAuth, 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.

Copy

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.

Copy

Was this helpful?

Yes