This article covers common authentication and authorization issues, what causes them, and how to address them.
Authentication and authorization failures usually surface as one of the following HTTP status codes.
A 401 means the request wasn't authenticated. Common causes:
- Missing or malformed Authorization header. Confirm the request includes
Authorization: <token>.
- Expired access token. The SDK refreshes or re-mints tokens automatically, so expiry usually points to raw REST calls or a token you stored and reused past its lifetime. Mint a new token and retry. See Token lifetime.
- Wrong token type for the call. For example, calling a Wix-app-restricted method with a visitor token.
- Revoked or invalid API key. Verify the key is still active in the Wix dashboard.
If none of these causes fit, the issue may be permissions related. Check the 403 causes too.
A 403 means the request was authenticated but the identity isn't allowed to perform the action. Common causes:
- Missing scope. The app or API key doesn't have the required scope. Check the method's required scopes in the API Reference and update your app setup or API key.
- API key can't access the site. A key scoped to specific sites only works for those sites. Calls targeting any other site are rejected. Check the key's site access in the Wix dashboard.
- Wrong role. The Wix user calling the method doesn't have the required role. See Permissions.
- Needs elevation. The method requires a Wix app identity, and the call is running as a visitor, member, or Wix user. See Elevation.
If you're using an API key, a 404 may indicate a site or account ID mismatch:
- Wrong site ID or account ID. Account-level APIs require an account ID; site-level APIs require a site ID. Make sure the request includes the right header (
wix-site-id or wix-account-id).
The following mistakes are frequent causes of auth failures:
- Mixing identity contexts. Be clear about which identity each piece of your code runs as. Each extension article in the Extensions Framework states this in its Authentication and permissions section.
- CORS errors in self-managed apps. Browser-based code calling Wix APIs directly may run into CORS. Route those calls through your backend.
- Expired or rotated app secrets. If your app secret was rotated in the Wix dashboard, update your backend with the new value.
- Scopes not granted at the current install. Adding a new scope to your app's setup doesn't retroactively grant it to existing installations. Adding a permission requires a major version release, and each existing installation gets the scope only after a Wix user accepts the update. Development sites are the exception: permission changes apply to them automatically.
- API key from the wrong account. Site-level calls only work with keys generated from the account that owns the site. If you're working with multiple accounts, check which account issued the key you're using.
- Looking for a REST flow to call as a Wix user. There isn't one. REST has no way to mint a Wix user token. If a call needs to run as the signed-in Wix user, such as from a dashboard extension, use the SDK with
dashboard.auth(). See Set Up a Wix Client.
When an auth call fails:
- Identify which identity the call actually runs as. This comes from where the code runs and which authentication method it uses.
- Compare that against the method's documented identity restrictions and required scopes in the API Reference.
- Confirm the token is the right type and is still valid (not expired, not revoked).
- For Wix user calls, verify the Wix user has the required role.
- For app calls, verify the scope is granted at the current install.