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 table below to find the right methods for your use case:
| Scenario | Methods to use | Learn more |
|---|---|---|
| Anonymous visitors | Handled automatically. Use generateVisitorTokens() for manual control. | Handle Visitors |
| Members with Wix-managed login | generateOAuthData(), getAuthUrl(), parseFromUrl(), getMemberTokens() | Handle Members with Wix-Managed Login |
| Members with custom login page | login(), register(), processVerification(), getMemberTokensForDirectLogin(), sendPasswordResetEmail() | Handle Members with a Custom Login Page |
| Members with external identity provider | getMemberTokensForExternalLogin() | Handle Members with Externally-Managed Login |
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.
| 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().
| Name | Type | Description |
|---|---|---|
oAuthData | OauthData | OAuth data generated by generateOAuthData(). |
| 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-managed 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.
| 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-managed 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 authenticating members through an external identity provider.
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.
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. |