**Tip:** Subscribe to the [App Instance Installed event](https://dev.wix.com/docs/rest/app-management/app-instance/app-instance-installed.md) to save the `instanceId` when your app is installed on a site.### Automatically log users in to your app When users access your app through iframes or external dashboards, Wix sends them to your endpoint with a [signed app instance query parameter](#app-instance-query-parameter). This data helps you understand which user is accessing your app, from which website, and what their role is, such as website owner or contributor. Consider these approaches for automatic login: - **Authenticate users by `instanceId`**: When users access your app, use the `instanceId` from the signed app instance parameter to create a user session or link to an existing account, eliminating the need for separate login credentials. - **Differentiate access levels by role**: Check the `permissions` field to determine if the current user is the site owner or a contributor, then grant appropriate access to features and data for that specific site. - **Enable seamless multi-site access**: Use the combination of `uid` (user ID) and `instanceId` to allow the same person to access multiple sites they manage without re-authenticating, while keeping each site's data separate. ### Manage users with more than one website Wix users can create thousands of websites under the same Wix account. There are many reasons for this, ranging from small businesses creating multiple websites for different products, to large partners creating thousands of websites for their clients. That's why apps must support users with multiple sites. Consider these approaches for multi-site support: - **Separate business data per site**: Use the `instanceId` as your primary database key to isolate data between sites, even when the site owner uses the same email address across multiple business websites. This ensures that Site A's customer data, inventory, or settings don't appear when the user accesses your app from Site B. - **Control dashboard access by role**: Check the `permissions` field in the app instance data to determine if the current user is the site owner or a contributor. Use this with the `instanceId` to ensure contributors can only access data for sites where they have permissions, preventing them from switching between sites they shouldn't see. - **Enable cross-site workflows for power users**: Some users manage multiple related sites and need to switch between them frequently. Implement a site-switching feature in your external dashboard by storing the relationship between the user's Wix account ID and multiple `instanceId` values, then let verified site owners toggle between their sites without returning to Wix. ### Detect site duplication The `originInstanceId` property indicates whether the current site was [duplicated from another site](https://support.wix.com/en/article/duplicating-your-site-1472847). 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. Consider these approaches for handling site duplication: - **Migrate data from the original site**: If your app stores site-specific data, use the `originInstanceId` to query your database for the original site's configurations, user data, or content, then copy it to the new `instanceId` to maintain continuity. - **Preserve user preferences across sites**: If your app has customizable settings, use the `originInstanceId` to inherit preferences like language, dashboard layouts, or feature configurations from the original site, then allow users to customize them for the duplicated site.
**Caution:** When a site is duplicated, a new app instance is created without triggering the consent flow. If your app uses [custom authentication (legacy)](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/custom-authentication-legacy.md), this means no refresh token is generated. To address this, you can either: - Prompt users to reinstall the app to trigger the consent flow and generate a refresh token. - [Authenticate using OAuth](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/authenticate-using-oauth.md) to generate an access token using the `instanceId`, app ID, and app secret.## Get the app instance ID The `instanceId` uniquely identifies your app on a site. You can get it from: - Get [Token Info method](https://dev.wix.com/docs/rest/app-management/oauth-2/token-info.md) - [Event payloads](https://dev.wix.com/docs/build-apps/develop-your-app/api-integrations/events-and-webhooks/about-webhooks.md) - [Service plugin metadata](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md) - [`getDecodedAppInstance()`](https://dev.wix.com/docs/velo/velo-only-apis/wix-application/get-decoded-app-instance.md) for Wix Blocks - [App instance query parameter](#app-instance-query-parameter) for iframes and external pages
**Important:** These methods don't return exactly the same set of properties.The method depends on your environment: - **Frontend environments**: Send tokens to your backend for decoding. See [Identify the App Instance in Frontend Environments](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/identify-the-app-instance-in-frontend-environments.md). - **Backend environments**: Extract directly from request data or decode from tokens. See [Identify the App Instance in Backend Environments](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/identify-the-app-instance-in-backend-environments.md). - **iframes and external pages**: [Parse the app instance query parameter](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/parse-the-app-instance-query-parameter.md).
**Warning:** Don't trust an `instanceId` sent to your backend as plain text, as it can be manipulated by an attacker.## Fetch instance data from Wix APIs Wix stores specific data about each app instance, which can be accessed using the following methods based on your use case: - **REST API and SDK**: Call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md) to get details about your app on the site, independent of user context (unlike the [app instance query parameter](#app-instance-query-parameter)). - **Velo API**: Call [`getDecodedAppInstance()`](https://dev.wix.com/docs/velo/velo-only-apis/wix-application/get-decoded-app-instance.md) to get the `instanceId` and the `vendorProductId`, which is the ID of the plan that the site owner purchased. This can only be called from Blocks frontend code. > **Note**: Wix Blocks apps should generally follow the same guidance as other apps, especially if the `instanceId` is required on the backend. ## App instance query parameter When users access your app through certain frontend interactions, Wix automatically sends app instance data as an encoded `instance` query parameter to your app's endpoints. This parameter contains the `instanceId` plus additional context like user information and site details. The data is signed to ensure it hasn't been tampered with. This is particularly useful for apps that need to know which site they're running on and who the current user is without making additional API calls. Apps that receive the app instance query parameter include: - iframe apps - External dashboard apps (when a user clicks **Open App**) - Apps with an external pricing page (when a user clicks **Upgrade App**) Learn how to [parse the app instance query parameter](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/parse-the-app-instance-query-parameter.md).
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.md 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 `instanceId` 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
aidparameter 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 theuid.
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"
}