CLI Documentation Notice
You're viewing documentation for the new Wix CLI, which we recommend for all new projects. Determine which CLI your project uses.
Previous CLI documentation:
For security reasons, app instance ID (instanceId) isn't directly accessible in site widgets or settings panels. Instead, you can securely extract it by sending a Wix access token to an HTTP endpoint. The endpoint can decode the token, get the instance ID or instance data, and perform any necessary business logic.
This article explains how to:
To securely identify the app instance:
Create an HTTP endpoint in your project's src/pages/api/ directory.
In your HTTP endpoint file, import the auth submodule from the Essentials API:
Depending on your use case, you may only need instanceId or you may need more detailed app instance data.
To extract instanceId:
In your Astro endpoint's GET function, call getTokenInfo() to extract instanceId from the access token.
To fetch instance data:
Elevate API call permissions to an app identity. Then, call getAppInstance(). Elevation is necessary because access tokens sent from site widgets are tied to a site visitor or member identity, which don't have access to instance data.
To pass a Wix access token from your site widget to your Astro endpoint:
Add a Site Widget Extension in the CLI. If you already have a site widget, skip to the next step.
In your site widget component file, import the httpClient submodule from the Essentials API.
For Editor React Component site widgets in component.tsx:
For Custom Element site widgets in element.tsx:
Call fetchWithAuth() to send a request to your Astro endpoint with a Wix access token.
For Custom Element site widgets with settings panels, you can also call fetchWithAuth() from your panel.tsx file to get instanceId in the settings panel.
Depending on your use case, the logic of your Astro endpoint will vary. For example, you may only need to extract instanceId and then use it to make a request to your own database. Alternatively, you may wish to request app instance data from Wix, in which case you'd need to elevate your access token.
See the relevant example for your use case:
instanceIdinstanceIdThe following example is based on an Astro endpoint located at src/pages/api/get-instance.ts. The endpoint extracts instanceId from the access token provided by the frontend request.
The following example is based on an Astro endpoint located at src/pages/api/get-instance.ts. The endpoint elevates permissions and requests instance data from Wix.
The following example creates an Editor React Component site widget that makes a request to the get-instance Astro endpoint.
The following example creates a custom element that makes a request to the get-instance Astro endpoint.