With Wix Headless, you can create a fully customized login experience for your members while 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.
Custom login uses Wix's authentication service while letting you design and control the entire login UI experience. This approach is best when you need to maintain a consistent branded experience throughout your site or app.
This article explains how to implement a custom login page using the JavaScript SDK.
You'll learn how to:
Note: If you don't need a custom login experience, you can use Wix-managed login, where Wix handles both the login UI and authentication process.
To authenticate and interact with Wix APIs, create a Wix client in your code. Install and import the Members API to create and manage a site's members. You can also import other APIs as needed and pass to your client.
Replace <YOUR_CLIENT_ID> with your OAuth app's Client ID from your Headless Settings.
Before showing a login form, check if the current visitor is already logged in:
If logged in, you can immediately make authenticated API calls. Otherwise, send them to your sign-up or login form.
Create custom forms in your app with fields for email and password. You can design these forms to match your branding exactly. Your page should be able to:
Tip: You can add reCAPTCHA protection to your custom login flows to help prevent fraud and abuse.
To sign up a new member, use the register() method with the email and password provided by the visitor:
If response.loginState is SUCCESS, exchange the session token for access and refresh tokens. Otherwise, handle failed authentication states.
To log in an existing member, use the login() method with the email and password provided by the visitor:
If response.loginState is SUCCESS, exchange the session token for access and refresh tokens. Otherwise, handle failed authentication states.
When authentication is successful, you need to exchange the session token for access and refresh tokens. This process is the same whether you're signing up a new member or logging in an existing member.
To exchange the session token for access and refresh tokens, call getMemberTokensForDirectLogin(), and then set the returned member tokens on your client:
Tip: After setting tokens, you can use myWixClient.members.getCurrentMember() to fetch the member's info.
When a sign-up or login attempt fails, the login() and register() methods return an object with a loginState property. Your code should handle each possible state to provide a smooth user experience. The possible values include:
SUCCESS: Authentication was successful.FAILURE: Authentication unsuccessful due to one of the following reasons, as indicated by the errorCode:
invalidEmail: The email address provided is invalid. Your code should present an error.invalidPassword: The password provided is invalid. Your code should present an error.emailAlreadyExists: The visitor attempted to sign up as a new member using an email address belonging to an existing member. Your code should present an error.resetPassword: The member needs to reset their password. Your code needs to send a password reset email.EMAIL_VERIFICATION_REQUIRED: Authentication requires email verification. Your code needs to process email verification.OWNER_APPROVAL_REQUIRED: The site owner needs to approve registration for the new member. Your code should present a notice to inform the visitor that their membership is pending. Once their membership is approved, the member can log in.Call the sendPasswordResetEmail() method to send a password reset email to a member. The method takes the member's email address and a URL to send the member to after they successfully change their password.
The redirectUri must be an allowed authorization redirect URI. When the member clicks the reset link in their email, they're taken to a Wix-managed password reset page. After successfully setting a new password, Wix redirects them to your specified URL.
For example, the following code sends a password reset email to john_doe@email.com, and once the member resets their password on the Wix-managed page, Wix redirects the member back to your page at http://www.my-site.com/password_changed.
If the loginState is EMAIL_VERIFICATION_REQUIRED, Wix sends an email with a verification code to the member. You need to create a form or prompt to collect this verification code from the member, and then use the processVerification() method to complete the verification:
If response.loginState is SUCCESS, exchange the session token for access and refresh tokens.
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.
Tip: Don't expose refresh tokens to the browser unnecessarily. For best security, handle token refresh on the server when possible.
To log a member out:
Get the logout URL from your Wix client:
Redirect the member to the logout URL:
This logs the member out and redirects them back to your app.
If you encounter issues with custom login, make sure that:
redirectUri parameter in sendPasswordResetEmail() matches one of your allowed authorization redirect URIs.