Identify the App Instance in a Site Widget Built with the CLI

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 a backend API. The backend can decode the token, get the instance ID or instance data, and perform any necessary business logic.

This article explains how to:

• Backend: Expose a backend API to identify the app instance.
• Frontend: Pass a Wix access token from your custom element to your backend.

Step 1 | Expose a backend API

To securely identify the app instance:

1. Add a Backend API Extension in the Wix CLI.

2. In the api.ts file of your backend API extension, import the auth submodule from the Essentials SDK:

   Copy

3. Depending on your use case, you may only need instanceId or you may need more detailed app instance data.

   • To extract instanceId:

     In the GET endpoint, call getTokenInfo() to extract instanceId from the access token.

   Copy

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

   Copy

Step 2 | Pass a Wix access token to your backend

To pass a Wix access token from your custom element to your backend:

1. Add a Site Widget Extension in the CLI. If you already have a site widget, skip to the next step.

2. In the element.tsx file of your site widget extension, import the httpClient submodule from the Essentials SDK.

   Copy

3. Call fetchWithAuth() to send a request to your backend with a Wix access token.

   Copy

Examples

Depending on your use case, the logic of your backend API 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:

• Backend: Extract instanceId
• Backend: Fetch instance data
• Frontend: Call your backend

Backend: Extract instanceId

The following example is based on a CLI backend API extension called get-instance. The API extracts instanceId from the access token provided by the frontend request.

Backend: Fetch instance data

The following example is based on a CLI backend API extension called get-instance. The API elevates permissions and requests instance data from Wix.

Frontend: Call your backend

The following example creates a custom element that makes a request to the get-instance endpoint.

See also

• About Site Widget Extensions
• About App Instances