Authenticate as an App Instance

Once installed on a site, your app can authenticate as an app instance to access resources that belong to that site, provided you requested the necessary permissions during app configuration.

This article explains how to authenticate as an app instance using the REST API, JavaScript SDK, and React SDK, following the basic OAuth protocol.

REST API

To authenticate as an app instance using the REST API:

1. Save your App ID and App Secret. Find these values in the Wix Dev Center under OAuth. Keep the secret confidential.

2. Get the relevant app instance ID. You can get the app instance ID from:

   • Client-triggered instance data
   • Webhook payloads
   • Service plugin (formerly SPIs) metadata

   If you subscribed to the Instance App Installed webhook, you likely already have the instanceId.

3. Send a request to Create Access Token. Include your app ID, app secret, and app instance ID in the HTTP body. For example:

   Copy

   1
   
   

4. Make an API request with the access token provided in the Authorization header.

The access token is valid for 4 hours. When it expires, make another request to Create Access Token.

JavaScript SDK

To authenticate as an app instance using the JavaScript SDK:

1. Save your App ID and App Secret. Find these values in the Dev Center under OAuth. Keep the secret confidential.

2. Get the relevant app instance ID. You can get the app instance ID from:

   • Client-triggered instance data
   • Webhook payloads
   • Service plugin (formerly SPIs) metadata

   If you subscribed to the Instance App Installed webhook, you likely already have the instanceId.

3. Create a WixClient using the AppStrategy bound to the app instance ID. For example:

   Copy

   1
   
   

4. Make an API request. Behind the scenes, the client makes a request to obtain an access token and incorporates it into the Authorization request header. For example:

   Copy

   1
   
   

   Tip: If a REST API isn't available in the SDK, you can still access it using the fetch() method.

The access token is valid for 4 hours. However, you don’t need to make any specific requests to refresh or create a new token, since the WixClient handles the logic.

React SDK

To authenticate as an app instance using the React SDK:

1. Save your App ID and App Secret. Find these values in the Dev Center under OAuth. Keep the secret confidential.

2. Get the relevant app instance ID. You can get the app instance ID from:

   • Client-triggered instance data
   • Webhook payloads
   • Service plugin (formerly SPIs) metadata

   If you subscribed to the Instance App Installed webhook, you likely already have the instanceId.

3. Wrap your app in a WixProvider using the AppStrategy bound to the app instance ID. For example:

   Copy

   1
   
   

4. Make an API request using useWixModules(). Behind the scenes, a request is made to obtain an access token using the details provided to the WixProvider. For example:

   Copy

   1
   
   

   Tip: If a REST API isn't available in the SDK, you can still access it using the useWixFetchWithAuth() hook.

The access token is valid for 4 hours. However, you don’t need to make any specific requests to refresh or create a new token, since the WixProvider handles the logic.

See also

• About Authentication for Wix Apps
• About Identities