Identify the App Instance in a Self-Hosted 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 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. Expose a backend API. You can build and deploy your backend API using any framework. The examples in this article are based on a Node.js server.

  2. In your backend API code, get the Wix access token from the authorization header.

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

    • To extract instanceId:

      Call Get Token Info to extract instanceId from the access token.

    Copy
    • To fetch instance data:

      Elevate the access token to an app identity. Then, call Get App Instance (SDK | REST). 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.

      The method of performing elevation varies depending on whether you're using the JavaScript SDK or REST API.

      JavaScript SDK

      Copy

      To learn more, see Elevate SDK Call Permissions with Self-Hosting.

      REST API

    Copy

    To learn more, see Elevate REST API Call Permissions with Self-Hosting.

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 self-hosted site widget extension with a custom element. If you already have a site widget, skip to the next step.

  2. In your custom element code, initialize a WixClient with the site authentication and host configuration.

    Copy
  3. Add the following line to the constructor of your custom element class to inject the Wix access token.

    Copy
  4. Import the httpClient submodule from the Essentials SDK.

    Copy
  5. Call fetchWithAuth() to send the access token to your backend.

    Copy

Tip: To get instanceId in the settings panel, initialize a WixClient with the editor authentication and host configuration. Then, call fetchWithAuth().

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

The following example creates a Node.js Express API called get-instance. The API extracts instanceId from the access token provided by the frontend request.

Copy

Backend: Fetch instance data with the JavaScript SDK

The following example creates a Node.js Express API called get-instance. The API receives an access token from the frontend, creates a client with elevated permissions, and then uses the elevated client to fetch the app instance data.

Copy

Backend: Fetch instance data with the REST API

The following example creates a Node.js Express API called get-instance. The API receives an access token from the frontend, uses the token to request a new access token with the permissions of an app, and then uses the new elevated access token to fetch the app instance data.

Copy

Frontend: Call your backend

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

Copy

See also

Did this help?