REST API Authentication

This article covers the REST-specific access token details for each identity. If you're using the JavaScript SDK, see Set Up a Wix Client instead.

The REST API authenticates every request with an access token sent in the Authorization header: Authorization: <token>. The token type depends on the identity the call should run as.

The sections below cover the token used for each identity and how to obtain it.

Visitor

For calls that run as an anonymous site visitor, such as browsing public content or managing the visitor's own cart.

• Token: OAuth visitor access token.
• How to get it:
  • Self-managed headless: Call the token endpoint with your OAuth app's client ID and the anonymous grant type. No login and no client secret are required. Wix returns an access token and a refresh token.
  • Self-managed apps: Don't mint visitor tokens, and there's no REST flow for them. The Wix site injects the current visitor's access token into a Wix client in the app's frontend extension, and calls go through the SDK. See Authenticate Custom Elements Using the Wix Client and Authenticate Embedded Scripts Using the Wix Client.

Member

For calls that run as a logged-in site member, such as reading their own data or managing their subscription.

• Token: OAuth member access token.
• How to get it:
  • Self-managed headless: Implement a member login option: redirect members to a Wix-hosted login page, build a custom login page backed by Wix's Authentication API, or authenticate against an external identity provider. Each flow ends with Wix issuing access and refresh tokens for the logged-in member.
  • Self-managed apps: The same injection mechanism as for visitors applies: the SDK client in the app's frontend extension receives the current member's token from the site automatically.

Wix user

REST doesn't support on-behalf-of-Wix-user authentication. To call Wix APIs as a Wix user (such as from a dashboard page), use the SDK with dashboard.auth(). See Set Up a Wix Client.

Wix app

For calls that run as the installed Wix app, using the app's granted scopes.

• Token: App token.
• How to get it:
  • Wix-managed apps: Wix issues the token automatically through the CLI hosting infrastructure.
  • Self-managed headless: Generate a client secret in the project's Headless Settings, then call Create Access Token with the client_credentials grant type and the OAuth app's client ID and secret. No instance ID is needed: a headless OAuth client belongs to exactly one site, so Wix resolves its installation for you. This is the recommended flow for admin operations scoped to a headless project's own site.
  • Self-managed apps: Call Create Access Token with the client_credentials grant type, sending your app ID, app secret, and app instance ID. Wix includes the instance ID in every event and service plugin request, for example the App Instance Installed event, and in the app instance query parameter for external pages and iframe extensions.

API key admin

For administrative server-to-server operations that don't depend on a user session, such as managing sites or importing data.

• Token: API key (long-lived).
• How to get it: An account owner or co-owner generates the key in the Wix dashboard with the scopes the calls need. You send the key in the Authorization header of REST requests.

Unlike the token-based identities above, an API key isn't bound to a single site, so each request must also identify its target: send a wix-site-id header for site-level calls or a wix-account-id header for account-level calls, but not both. For how to retrieve these IDs, see Generate an API Key.

API keys are used in partner workflows and as an alternative to the OAuth client_credentials flow for admin operations in self-managed headless projects. They aren't available to third-party Wix apps.

Token expiry

Access tokens are short-lived and must be refreshed before they expire. API keys are long-lived and remain valid until revoked or rotated in the Wix dashboard.

For REST callers: if a call returns 401, the token has likely expired. For visitor and member tokens, call the token endpoint with your refresh token and the refresh_token grant type to get a new access token. For app tokens, call Create Access Token again with the client_credentials grant type and your credentials.

Credential security

Apps and headless projects hold credentials (app ID, app secret, API keys) to authenticate. Treat them like passwords:

• Store them in environment variables, not hardcoded in source.
• Don't commit them to version control.
• Don't expose them to frontend code; they belong in your backend.
• Use separate credentials for development and production.
• Rotate them if you suspect they've been compromised.

In Wix-managed apps and Wix-managed headless projects, Wix manages these credentials for you.