Notes:
This authentication strategy is used with a Wix Client to authenticate API calls using OAuth tokens. When using this strategy, the requester's identity is that of the corresponding visitor or member, and permissions are determined by their assigned roles.
Different methods are designed for different authentication scenarios. Use the decision tree to find the right flow, then the table below for the methods that flow uses.
On a custom page you build, you can offer several of these methods together, such as an email and password form alongside a Google button.
| Scenario | Methods to use | Learn more |
|---|---|---|
| Anonymous visitors | Handled automatically. Use generateVisitorTokens() for manual control. | Handle Visitors |
| Members with a Wix login page | generateOAuthData(), getAuthUrl(), parseFromUrl(), getMemberTokens() | Add a Wix Login Page (JS SDK) |
| Members with a custom login page | login(), register(), processVerification(), getMemberTokensForDirectLogin(), sendPasswordResetEmail() | Build a Custom Login Page (JS SDK) |
| Sign in with an identity provider (Wix runs it) | generateOAuthData(), getAuthUrl() with the idp option, parseFromUrl(), getMemberTokens() | Sign In with Google or Facebook (JS SDK) |
| Bring your own identity provider (you run it) | getMemberTokensForExternalLogin() | Bring Your Own Identity Provider |
After authenticating, use token management methods to store and refresh tokens, and session management methods to speed up redirects to Wix pages.
Creates an authentication strategy object that uses OAuth for visitor or member authentication.
To retrieve your client ID, go to the Headless Settings of your project dashboard.
Tip: For Wix-managed headless projects, you can also find your client ID locally as the appId in your project's wix.config.json file.
| Name | Type | Description |
|---|---|---|
clientId | string | The Wix Headless client ID. |
tokens | Tokens | Optional. The access and refresh tokens to use for authentication. |
siteId | string | Optional. The ID of the Wix site to make API calls to. |
OAuthStrategy
Use these methods to manage anonymous visitor sessions.
Generates visitor access and refresh tokens.
Use this method when creating a session for visitors using the OAuth authentication strategy. The client automatically calls this method when you make your first API call, but you can call it explicitly to generate tokens before making any calls.
To generate new tokens without checking whether the current access token is valid, use renewToken() instead.
| Name | Type | Description |
|---|---|---|
tokens | Tokens | Optional. Existing tokens to validate or renew. If provided, returns the same tokens if valid, or new tokens if expired. |
Use these methods when redirecting members to a Wix-hosted login page for authentication.
Generates the data required for an OAuth flow.
Call this method on the page that initiates the login. Store the returned data and use it later on the login callback page when calling getMemberTokens(). Learn more about storing tokens.
| Name | Type | Description |
|---|---|---|
redirectUri | string | The URI to redirect to after authentication is complete. |
originalUri | string | Optional. The URL of the page where the authentication request originated from. Use this to redirect back from the callback page. |
| Name | Type | Description |
|---|---|---|
state | string | A randomized string to be used in the OAuth flow. |
redirectUri | string | The URI to redirect to after authentication is complete. |
originalUrl | string | The URL of the page where the authentication request originated from. |
codeVerifier | string | A randomized string to use for PKCE authentication. |
codeChallenge | string | A SHA256 hash of codeVerifier to use for PKCE authentication. |
Gets a URL to redirect visitors to for Wix authentication.
Call this method using the OAuthData returned from generateOAuthData(). After the visitor authenticates, they're redirected to the redirectUri specified in the oauthData. The authorization code and state parameter are appended to the URL and can be parsed using parseFromUrl().
To send members straight to an external identity provider, such as Google, instead of the Wix login form, pass an idp in the options parameter.
Note: Custom OpenID Connect (OIDC) connections (idp: { connectionId }), such as your own SSO provider, are available only for Wix Studio enterprise and Wix Channels sites. Eligible sites have SSO settings in the dashboard for configuring a connection. To learn more, see Setting up SSO.
| Name | Type | Description |
|---|---|---|
oAuthData | OauthData | OAuth data generated by generateOAuthData(). |
options | object | Optional. Additional options for the authentication URL. |
options.prompt | string | Optional. Whether to display the Wix login page ('login', the default) or to skip it and reuse an existing member session if one exists ('none'). |
options.responseMode | string | Optional. How the code and state are returned to your callback URL: in the URL 'fragment' (the default), a 'web_message', or a 'query' string. |
options.sessionToken | string | Optional. A session token used to maintain the visitor's identity through the login redirect. |
options.idp | string | object | Optional. Authenticate with an external identity provider instead of the Wix login form. Pass 'google' or 'facebook' to sign in with that provider, or { connectionId: '<CONNECTION_ID>' } to use a custom OpenID Connect (OIDC) connection. |
| Name | Type | Description |
|---|---|---|
authUrl | string | URL to redirect the browser to for Wix authentication. |
Parses the code and state fragments from the browser's current URL.
Call this method on the login callback page after the visitor returns from the Wix-hosted login page. Use the returned data to verify the authentication was successful and as arguments when calling getMemberTokens().
| Name | Type | Description |
|---|---|---|
code | string | The authorization code appended to the callback page URI by the Wix server. |
state | string | The state parameter value appended to the callback page URI by the Wix server. |
error | string | Optional. Error, if one occurs. |
errorDescription | string | Optional. Error description, if one occurs. |
Retrieves and authenticates a site member's access and refresh tokens.
Call this method on the login callback page after parsing the URL using parseFromUrl(). Pass the stored OAuthData from generateOAuthData() and the parsed URL information.
| Name | Type | Description |
|---|---|---|
code | string | The authorization code from parseFromUrl(). |
state | string | The state parameter value from parseFromUrl(). |
oAuthData | OauthData | OAuth data from generateOAuthData(). |
Use these methods when building your own login UI instead of redirecting to Wix.
Logs in an existing member using an email address and password.
The method returns a StateMachine object indicating the login result. If loginState is SUCCESS, retrieve the session token from data.sessionToken and pass it to getMemberTokensForDirectLogin().
If loginState is EMAIL_VERIFICATION_REQUIRED, an email with a verification code is sent automatically. Use processVerification() to complete the login.
| Name | Type | Description |
|---|---|---|
email | string | Member's email address. |
password | string | Member's password. |
captchaTokens | CaptchaTokens | Optional. reCAPTCHA tokens. |
Registers a new member using an email address and password.
The method returns a StateMachine object indicating the registration result. If loginState is SUCCESS, retrieve the session token from data.sessionToken and pass it to getMemberTokensForDirectLogin().
If loginState is EMAIL_VERIFICATION_REQUIRED, an email with a verification code is sent automatically. Use processVerification() to complete registration.
| Name | Type | Description |
|---|---|---|
email | string | Registering member's email address. |
password | string | Registering member's password. |
profile | IdentityProfile | Optional. Details about the registering member. |
captchaTokens | CaptchaTokens | Optional. reCAPTCHA tokens. |
Processes a verification code from a member.
Call this method when the loginState property returned by login() or register() is EMAIL_VERIFICATION_REQUIRED. An email containing a verification code is sent automatically to the member. Use that code when calling this method.
| Name | Type | Description |
|---|---|---|
verificationCode | string | The verification code from the email sent to the member. |
Retrieves and authenticates a site member's access and refresh tokens from a session token.
Call this method after a successful login(), register(), or processVerification() call. Pass the session token from the returned StateMachine.data.sessionToken, then use setTokens() to set the tokens as the client's active tokens.
Important: This method uses a hidden iframe internally to perform the PKCE token exchange. This works on desktop browsers only. For mobile-compatible authentication, use a full-page redirect flow instead.
| Name | Type | Description |
|---|---|---|
sessionToken | string | The session token from a successful login(), register(), or processVerification() call. |
Sends a password reset email to a member.
The email contains a link to a Wix-hosted page where the member can set a new password.
| Name | Type | Description |
|---|---|---|
email | string | Member's email address. |
redirectUri | string | The URI to redirect to after the password is reset. |
Use this method when you bring your own identity provider and run its login yourself.
Retrieves and authenticates a site member's access and refresh tokens given a member ID.
This is an administrative method that bypasses the need for a session token. Call it from a secure server environment only.
A member ID can be retrieved using queryMembers() with any externally identifiable field such as email or phone number.
| Name | Type | Description |
|---|---|---|
memberId | string | Member ID. |
apiKey | string | API key with permissions for Wix Contacts & Members. |
Use these methods to manage tokens for any authentication flow.
Gets the active tokens from the client.
Sets tokens as the active tokens for the client.
| Name | Type | Description |
|---|---|---|
tokens | Tokens | The tokens to set. |
Generates a new access token for an existing refresh token without checking whether the current access token is valid.
To generate a new access token only if the current access token is invalid, use generateVisitorTokens() instead.
| Name | Type | Description |
|---|---|---|
refreshToken | RefreshToken | The refresh token to use. |
Gets the client's authorization headers.
Authorization headers.
Indicates whether the current visitor is a logged-in member.
true if the current visitor is logged in, false otherwise.
Logs out the current logged-in site member.
| Name | Type | Description |
|---|---|---|
originalUrl | string | The URL to redirect to after logging out. |
| Name | Type | Description |
|---|---|---|
logoutUrl | string | URL to redirect the browser to in order to initiate the logout. |
Speed up redirects to Wix pages like checkout by pre-creating session cookies.
By default, createRedirectSession() creates a session cookie on-demand, which adds latency. To avoid this, check if a cookie exists using sessions.isSessionSynced(). If not, you can call sessions.syncWithWixPages() to create a cookie before calling createRedirectSession().
Checks whether a session cookie exists for the redirect and is in force.
true if a current session cookie exists, false if no cookie exists or the existing cookie is expired.
Creates a session cookie if none exists.
Note: This method uses an iframe internally to create session cookies. On mobile browsers that block 3rd-party cookies, such as Safari and Chrome on iOS, the iframe may be blocked, preventing the session cookie from being set. For mobile-compatible authentication, use a full-page redirect flow instead.
Gets a Wix reCAPTCHA site key for use with a visible reCAPTCHA.
Type: string
Gets a Wix reCAPTCHA site key for use with an invisible reCAPTCHA.
Type: string
| Property | Type | Description |
|---|---|---|
accessToken | object | The access token. |
accessToken.value | string | Token string value. |
accessToken.expiresAt | number | When the token expires (Unix timestamp). |
refreshToken | object | The refresh token. |
refreshToken.value | string | Token string value. |
refreshToken.role | string | Token role. One of visitor, member, or none. |
| Property | Type | Description |
|---|---|---|
data | object | Session token for logged-in member as {sessionToken: string}. |
loginState | string | One of: FAILURE, EMAIL_VERIFICATION_REQUIRED, OWNER_APPROVAL_REQUIRED, SUCCESS. |
errorCode | string | One of: invalidEmail, invalidPassword, resetPassword, missingCaptchaToken, emailAlreadyExists, invalidCaptchaToken. |
error | string | Error message. |
| Property | Type | Description |
|---|---|---|
invisibleRecaptchaToken | string | Token for invisible reCAPTCHA. |
recaptchaToken | string | Token for visible reCAPTCHA. |
| Property | Type | Description |
|---|---|---|
firstName | string | First name. |
lastName | string | Last name. |
nickname | string | Nickname. |
picture | string | Picture. |
emails | string[] | Email addresses. |
phones | string[] | Phone numbers. |
labels | string[] | Labels. |
language | string | Language. |
privacyStatus | string | One of: UNDEFINED, PUBLIC, PRIVATE. |
customFields | object | Custom fields as an object where the keys are the field name and the values are the field values. |
Last updated: 22 July 2026