Identify the App Instance in a Site Extension

For security reasons, app instance ID (instanceId) isn't directly accessible in site extensions 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:

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

Step 1 | Create an HTTP endpoint

To securely identify the app instance:

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

2. In your HTTP 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 extensions 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 site extension to your Astro endpoint:

1. Add a custom element site extension. If you already have one, skip to the next step.

2. In your site extension component file, import the httpClient submodule from the Essentials API.

   In element.tsx:

   Copy

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

   Copy

For custom elements with settings panels, you can also call fetchWithAuth() from your panel.tsx file to get instanceId in the settings panel.

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
• Custom Element: 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.

Custom Element: 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 Extensions in the Wix CLI
• About App Instances