Identify the App Instance in a Site Widget

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 Astro 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:

• Backend: Create an Astro endpoint to identify the app instance.
• Frontend: Pass a Wix access token from your custom element to your Astro endpoint.

Step 1 | Create an Astro endpoint

To securely identify the app instance:

1. Create an Astro endpoint in your project's src/pages/ directory.

2. In your Astro endpoint file, import the auth submodule from the Essentials API:

   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 your Astro endpoint's GET function, 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 Astro endpoint

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

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

   Copy

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

   Copy

Examples

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:

• Astro Endpoint: Extract instanceId
• Astro Endpoint: Fetch instance data
• Frontend: Call your Astro endpoint

Astro Endpoint: Extract instanceId

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

Astro Endpoint: Fetch instance data

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.

Frontend: Call your Astro endpoint

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

See also

• About Site Widget Extensions
• About App Instances