Handle Members with Wix-Managed Login

With Wix Headless, you can authenticate members on a site or app using Wix as your identity provider. This allows members to securely sign in and access content or features that are specific to their account, such as their profile, saved items, order history, or other private information.

Wix-managed login uses the OAuth 2.0 protocol with PKCE (Proof Key for Code Exchange) for secure authentication. If you're new to these concepts, see OAuth 2.0 and PKCE explained.

This article explains how to implement Wix-managed member login using the JavaScript SDK.

You'll learn how to:

• Generate and store OAuth data for the login flow.
• Redirect members to the Wix-managed login page.
• Handle the callback and exchange the authorization code for member tokens.
• Set tokens for authenticated API calls as the logged-in member.
• Refresh access tokens using the refresh token.
• Log out members using the Wix-managed logout URL.

Prerequisites

• Create a Wix Headless project
• Create an OAuth app for visitors and members
• Add a Wix pages domain
• Add an allowed redirect domain

Login flow

When using Wix-managed login, you're responsible for writing the code to start the login and handle the response. Wix handles the login UI and authentication.

The login flow looks like this:

1. A member starts the login on your site or app. For example, they click a "Log in" button. Your site or app generates the required OAuth data using your Wix client and stores it securely. Then, it redirects the member to the Wix-managed login page.
2. The member logs in on the Wix-managed login page. Wix then redirects the member back to your site or app using a callback URL you've configured. This URL must be one of your allowed authorization redirect URIs.
3. In your callback handler, process the request, verify the login, and exchange the code for member tokens.

Step 1 | Set up a Wix client

To authenticate and interact with Wix APIs, create a Wix client in your code:

Replace <YOUR_CLIENT_ID> with your OAuth app's Client ID from your Headless Settings.

Step 2 | Generate OAuth data

Use your Wix client to generate the data needed for the OAuth flow.

The method takes the following 2 parameters:

• redirectURI: The URL to which Wix redirects the member after login. This must exactly match one of your allowed authorization redirect URIs configured in your Headless Settings.
• originalURI: The URL where the member started the login flow. The Wix-managed login flow returns the member to this location after authentication.

The method returns an object with the following properties, used for OAuth 2.0 with PKCE (Proof Key for Code Exchange) security:

• state: A unique string to verify the login request.
• codeVerifier: A random string for PKCE authentication.
• codeChallenge: A SHA256 hash of codeVerifier for PKCE.
• redirectURI: The redirect URI you passed.
• originalURI: The original URI you passed.

Example:

Step 3 | Store OAuth data

Store the OAuth data securely for use after login. For example, use localStorage or a cookie:

Step 4 | Redirect members to Wix login

To redirect members to the Wix login:

1. Request the login URL from your Wix client:

   Copy

   Important: For this request to succeed, you must publish the Wix site connected to your Headless project. Wix uses the published site to display the login page. To do this, open your project dashboard, select Design Site from the left panel, and then click Publish.

2. Redirect the member to the Wix login page:

   Copy

This redirects site members to the Wix-managed login page, where Wix handles the login process.

Step 5 | Handle callback and perform token exchange

Once members log in, Wix redirects them back to your site or app along with information you can use to confirm the login and generate member tokens for frontend API calls.

If the login was successful, the callback URL contains a fragment that includes code= and state=. If the login failed, the URL contains a fragment that includes error= and error_description=.

In your callback handler:

1. Retrieve the stored OAuth data:

   Copy

2. Parse the callback URL:

   Copy

3. Exchange the code for tokens:

   Copy

The returned tokens object includes:

• Access token: Used to make authenticated API calls.
• Refresh token: Used to get a new access token when the current token expires.

Step 6 | Set and refresh tokens for the client

Set the tokens on your Wix client to authenticate API calls as the logged-in member:

Access tokens expire after a short time for security reasons. When this happens, you can use a refresh token to request a new access token without asking the member to log in again.

Your API layer should handle this automatically. Set up your logic to detect when an access token has expired, use the refresh token to get a new one, and then retry the original request.

Logging a member out

To log a member out:

1. Get the logout URL from your Wix client:

   Copy

2. Redirect the member to the logout URL:

   Copy

This logs the member out and redirects them back to your app.

Troubleshooting

If you encounter issues with Wix-managed login, make sure that:

• You're using the correct client ID.
• The redirectUri parameter passed to generateOAuthData() is listed in your allowed authorization redirect URIs, and that the values match exactly.