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:
To securely identify the app instance:
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.
In your backend API code, get the Wix access token from the authorization
header.
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.
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
To learn more, see Elevate SDK Call Permissions with Self-Hosting.
REST API
To learn more, see Elevate REST API Call Permissions with Self-Hosting.
To pass a Wix access token from your custom element to your backend:
Add a self-hosted site widget extension with a custom element. If you already have a site widget, skip to the next step.
In your custom element code, initialize a WixClient
with the site authentication and host configuration.
Add the following line to the constructor of your custom element class to inject the Wix access token.
Import the httpClient
submodule from the Essentials SDK.
Call fetchWithAuth()
to send the access token to your backend.
Tip: To get instanceId
in the settings panel, initialize a WixClient
with the editor authentication and host configuration. Then, call fetchWithAuth()
.
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:
instanceId
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.
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.
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.
The following example creates a custom element that makes a request to the get-instance
endpoint.