A permission is the right to perform a specific kind of operation on Wix, such as reading products, managing bookings, or managing orders. Every API call is checked against the caller's permissions before it runs, and succeeds only when the caller's permissions include what the method requires.
Wix expresses permissions as scopes and roles. Scopes apply to apps and API keys, and roles apply to Wix users.
Scopes define which API operations an app or API key can perform:
- For apps: Scopes are declared in the app's setup and granted by a Wix user when the app is installed. Learn how to Configure Permissions for Your App.
- For API keys: Scopes are configured when the key is created. Learn how to Generate an API Key.
Each method in the API Reference lists the permission scopes it supports. To call the method, the app or API key needs at least one of the listed scopes. The same applies for receiving platform events.
Roles define what a Wix user is allowed to do in a specific site or account context. The site owner, or a collaborator with the right permissions, assigns roles to other Wix users.
To learn more, see Roles & Permissions.
A method may require a scope, a role, or both. A call passing the scope check can still fail if the active Wix user's role doesn't allow the action.
When an app authenticates on behalf of a Wix user, the effective permissions are the intersection of the app's scopes and the user's role: the app can't exceed what the user's role allows, and the user can't exceed what the app's scopes allow.
Sometimes you need to call a method that requires more permissions than the current caller has. Two tools cover this:
- Elevation: Lets a specific call run with higher permissions than the caller's, in backend code. Use it for individual privileged operations inside a flow that otherwise runs as the caller. Every development path supports elevation, though the mechanics differ by path.
- API keys: For backend-only, server-to-server admin work, authenticate with an API key with the required scopes instead of elevating calls.
Where a caller's permissions come from, and how you grant them, depends on your development path:
- Sites: Site code doesn't use scopes. Calls carry the permissions of the current visitor, member, or Wix user, and a Wix user's permissions come from their role. See Roles & Permissions.
- Wix-managed headless projects: Calls made as the Wix app use its granted scopes. Other calls carry the permissions of the resolved caller identity.
- Self-managed headless projects: Visitor and member calls carry those identities' permissions. Admin calls authenticate with the OAuth app's client credentials, or with an API key and its configured scopes.
- Wix-managed apps: App permissions come from the scopes granted at installation. When the app acts on behalf of a Wix user, the scopes intersect with the user's role. See Configure Permissions for Your App.
- Self-managed apps: App permissions come from the scopes granted at installation. When the app acts on behalf of a Wix user, the scopes intersect with the user's role. See Configure Permissions for Your App.
- Blocks apps: The same model as Wix-managed apps: scopes granted at installation, intersected with the Wix user's role when acting on a user's behalf. See Configure Permissions for Your App.