Configure Permissions for Your App

This article explains how to identify the required permissions and add them to your app configuration. For more information, see About Permissions.

Step 1 | Identify required permissions

To identify which permissions your app requires:

1. Go to the REST API, JavaScript SDK, or Velo (for Wix Blocks) reference.

2. Search for the endpoints or methods your app uses.

3. Find the supported permission scopes under Permission Scopes:

   

4. Select one of the permission scopes listed to include in your app. You can click on a scope to prompt the addition to your app, as described in the next section.

Step 2 | Add permissions to your app

To add permissions to your app:

1. Go to Permissions in your app's dashboard.

2. Click Add Permissions.

3. Search or filter for the relevant scope.

4. Select the relevant scopes from the results.

   Tip: Keep in mind that some high-level permission scopes, like Read Stores - All Read Permissions, encompass multiple other permission scopes, such as Read Products and Read Orders. Therefore, you don't need to add the lower scopes separately.

5. Click Save.

When a site owner installs your app, they're prompted to approve the specified permissions.

Migrate legacy permissions to scopes

If your app still has permissions from before Wix introduced permission scopes, those permission IDs use the legacy format without the SCOPE. prefix. For example, WIX_STORES.READ_PRODUCTS is the legacy form of SCOPE.DC-STORES.READ-PRODUCTS.

Legacy-format IDs still appear on the Permissions page and when Wix users install your app, but they aren't valid scopes. Wix doesn't grant them at install, so API calls that need those permissions fail even though the permission looks configured.

You can confirm a legacy ID by calling List App Permissions. If any appPermissions[].permission.permissionId value is missing the SCOPE. prefix, that permission is in the legacy format. This is different from the WIX_* values in instance.permissions from Get App Instance, which are the individual permissions a valid scope grants.

If any of your app's permissions are in this legacy format, a Migrate to Scopes banner appears at the top of the Permissions page. Click Migrate to Scopes to convert them to their scope equivalents. If the button is disabled, your app isn't currently in a state that allows updates, such as while it's in review. Wait until you can update the app, then migrate.

Step 3 | Verify granted permissions

The permissions you configure for your app aren't always the same as the permissions granted to an app instance on a specific site. If you add a permission after a Wix user installs your app, their instance doesn't have it until they approve the change.

To compare the permissions your app requests with the permissions granted on a site:

1. Call List App Permissions with your app's appId to retrieve the permission scopes your app requests. Each result returns a scope ID in appPermissions[].permission.permissionId, such as SCOPE.DC.MANAGE-YOUR-APP.

   Tip: Pass consistent=true to retrieve the most recent permissions, including changes you just saved.

2. Call Get App Instance to retrieve the permissions granted on the site. The response's instance.permissions array lists the granted permissions.

3. Compare the results. The two methods don't necessarily return identical strings: List App Permissions returns permission scope IDs, while instance.permissions lists the individual permissions that those scopes grant. For example, the SCOPE.DC.MANAGE-YOUR-APP scope grants the WIX_DEVELOPERS.MANAGE_APP_INSTANCE permission. To see which permissions a scope covers, check the Permissions and Permission Scopes sections of the relevant API reference.

Note that these methods require different identities. List App Permissions requires an API key with the account-level Manage Custom Apps permission from the account that owns the app. Get App Instance must be authenticated as your app on the site you're checking.

If a permission you configured isn't granted to the instance:

• On a development site: Wait a few minutes and check again. Permission changes apply automatically, but they aren't always immediate.
• On a site with a released version of your app: Adding permissions requires a major version. Wix users who installed your app before the update need to update it and approve the new permissions.