AppStrategy
Important: This strategy is intended for use with Wix apps.
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
1
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. |
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. |
Note: You must provide either instanceId or refreshToken.
Returns
AppStrategy
Functions
getInstallUrl()
Retrieves the Wix app install URL.
Use this function to intiate 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
1
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
1
Parameters
| Name | Type | Description |
|---|---|---|
url | string | The URL containing the authorization code to be processed. |
Returns
accessToken, refreshToken, instanceId
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.
1
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.
1
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.
1