Extract App Instance IDs From Backend Requests

When developing backend extensions for an app or web methods, you may need to know the ID of the app instance (instance ID) making the request to your backend. This ID is encoded in a token sent along with the request.

Use cases

The following are examples of use cases that require the instance ID:

Store user generated content in an external databse

Allow users to create content that's specific to the site where it's installed, storing this content in an external database. Using instance IDs, you can associate the content with the site where it was created, and ensure that the content is displayed only on the site where it was created.

Configure instance-specific settings

Allow users to configure settings in your app that are specific to the instance of the app on the site, such as color scheme, or layout. Using instance IDs, you can store and retrieve unique configurations for each site using your app.

Implement usage-base billing

Implement usage-based billing based on the instance ID of the site where the app is installed. Using instance IDs, you can track the usage of your app on a per-site basis and bill the site owner accordingly, such as by the number of requests made to the app or the amount of data stored in the app.

When you need the instance ID

When you are working with Wix APIs or Data Collections, you generally don't need to extract the instance ID manually. The instance ID is encoded in the tokens that are sent with the request, and Wix APIs automatically extract the instance ID from the token and include it in the request context. However, if you are working with external APIs or databases, you might need to extract the instance ID manually.

Security considerations

The instance ID is encoded in the token sent with the request, and it is also sent with the request as plain text. You should not trust the instance ID sent as plain text, as it can be manipulated by an attacker. Always use the method described below to extract the instance ID from the token sent with the request.

How to extract the instance ID from the request

To extract the instance ID from the request to your backend extension, use the getTokenInfo() function from the @wix/essentials package. This function returns the information encoded in the currently active token (the token sent with the request). For an example of how to do this, see the getTokenInfo() documentation.

Did this help?