When your app is installed on multiple Wix sites, you need a way to determine which site is making a request. This is done using the app instance.
An app instance represents a unique installation of your app on a specific Wix site. Each app instance is identified by a unique instanceId, which remains the same even if the app is uninstalled and reinstalled.
This article explains how app instances work and how to use them effectively.
Tip: Subscribe to the App Instance Installed event to save instanceId when your app is installed on a site. Use it to handle site-level logic or create an access token to call Wix APIs.
Identifying the app instance enables you to manage site-specific logic. For example, you can:
In some cases, the instanceId alone is enough to query your database and perform business logic. In other cases, you might need to fetch instance data from Wix APIs.
The instanceId uniquely identifies your app on a site. You can retrieve it from:
getDecodedAppInstance() for Wix Blocksinstance query parameter for iframes and external pagesThe method used to retrieve the instanceId depends on the environment and scenario:
instance query parameter to a secure backend, and then decode it to get the instanceId. For detailed examples, see Identify the App Instance in Frontend Environments.instanceId directly from request data, such as for webhooks and service plugins, or decode it from a Wix access token. For detailed examples, see Identify the App Instance in Backend Environments.Warning: Don't trust an instanceId sent to your backend as plain text, as it can be manipulated by an attacker.
Wix stores specific data about each app instance, which can be accessed using the following methods based on your use case:
Important: These methods don't return exactly the same set of properties.
You can get app instance data by calling Get App Instance (SDK | REST). The method returns details about your app on the site, independent of user context (unlike the encoded query parameter).
In Wix Blocks frontend code, you can retrieve app instance data using the Velo API method getDecodedAppInstance(). The method returns the instanceId and the vendorProductId, which is the ID of the plan that the site owner purchased.
Note: Wix Blocks apps should generally follow the same guidance as other apps, especially if the instanceId is required on the backend. For details, see the relevant article:
When a site visitor accesses certain extensions or external pages through a frontend action, Wix automatically provides data about the app instance as an encoded query parameter, instance, to your app endpoints. The instance query parameter includes the instanceId along with site and user information. The data is also signed to ensure its integrity and authenticity.
Apps that receive the encoded query parameter include:
Example use cases for instance data provided by the encoded query parameter include:
instanceId as the app iframe.The encoded instance parameter is composed of two parts separated by a dot:
Here's an example of the encoded instance parameter:
// Signature Data
vrinSv2HB9tqbnJ6RSwoMgVamAIxpmmsA0I6eAan960.eyJpbnN0YW5jZUlkIjoiYWZmNTAxNmQtMjkxNC00ZDYzLWEzOGMtYTZk...For examples on how to parse the parameter, see Parse the Encoded App Instance Parameter.
Once decoded, you'll have access to the following data:
| Field | Description |
|---|---|
instanceId | The instance ID of the app within Wix. Read more about the App Instance ID below. |
signDate | The date of the payload signature. |
uid | The ID of the Wix user or site member who is logged in. |
permissions | The permission set of the Wix user or site member: Note: To check if the site owner is logged in, compare the uid to the siteOwnerId property. |
ipAndPort (deprecated) | The user's current IP address and port number. |
vendorProductId | (Optional, appears if the site owner upgraded the app) The Plan ID of the package the site owner purchased. |
aid | The ID of an anonymous site visitor. |
originInstanceId | The instance ID of the app in the original site. This property is only relevant for duplicated sites. |
siteOwnerId | The ID of the site owner. When this value is the same as the uid, it means the site owner is logged in. |
Warning: For dashboard security, restrict access if the aid parameter is returned, indicating that the user attempting to access the dashboard is anonymous. This applies to users who aren't the site's owner or collaborators, identifiable by the uid.
Note: The siteOwnerId associated with a particular instanceId may change. If a site owner transfers ownership to another user, the existing instanceId becomes linked to the new owner. For instance, if User A transfers the site to User B, the app retains its instanceId but becomes associated with User B's siteOwnerId.
{
"instanceId": "bf296da1-75ce-48e6-9f72-14b7148d4fa2",
"signDate": "2015-12-10T06:57:37.201Z",
"uid": "da32cbf7-7f8b-4f9b-a97e-e67f3072ce92",
"permissions": "OWNER",
"ipAndPort": "91.199.119.13/35734",
"vendorProductId": null,
"originInstanceId": "c38e4e00-dcc1-433e-9e90-b332def7b342",
"siteOwnerId": "da32cbf7-7f8b-4f9b-a97e-e67f3072ce92"
}The originInstanceId property indicates whether the current site was duplicated from another site. If originInstanceId is present, it contains the instanceId of the original installation. If it's missing or empty, the site wasn’t duplicated. Wix includes this property when you retrieve instance data using the REST API, SDK, encoded instance query parameter, or the app instance installed event.
Detecting site duplication helps you to:
This is especially relevant for apps with stored configurations or content that should persist across duplicated sites.
Caution: When a site is duplicated, a new app instance is created without triggering the consent flow. If your app uses custom authentication (legacy), this means no refresh token is generated. To address this, you can either:
instanceId, app ID, and app secret.