Handle Members with Custom Login

You may want to implement a login flow for your site or app's members. This allows members to access their personal content.

Wix Headless offers the ability to redirect visitors to a Wix-managed page for handling member login. However, you might prefer to create your own custom login interface as part of your external site or app as described here.

Prerequisites

• Create a project
• Create an OAuth app for visitors and members
• Add an allowed authorization redirect URI
• Set the login URL

Create a frontend login component

Create a frontend login/sign-up component for the site or app you are building on the platform of your choice. Ensure that your UI prompts visitors for an email address and password.

Sign up a new member

To register a new member using an email address and password the site visitor provides, call the Register V2 endpoint.

When calling the Register V2 endpoint, send the following parameters:

• loginId.email: Registering member's email address.
• loginId.password: Registering member's password.
• [profile]: Registering member's profile.

1
curl --location 'https://www.wixapis.com/_api/iam/authentication/v2/register' \
2
--header 'authorization: <ACCESS_TOKEN>' \
3
--header 'content-type: application/json' \
4
--data '{
5
  "loginId":{
6
    "email": "john@doe.com"
7
  },
8
  "password": "verySecurePassword",
9
  "profile": {
10
    "firstName": "John",
11
    "lastName": "Doe",
12
    "nickname": "Johnny Boy"
13
  }
14
}'

The Register V2 endpoint initiates a new member registration and returns a response containing the state of the registration operation and associated tokens.

The Register V2 endpoint's response contains the following:

• state: The current state of the registration process. Use this state value to determine the next step in the registration process.
• sessionToken: If the state value is 'SUCCESS', use the sessionToken to get the site members tokens.
• stateToken: If the state value is not 'SUCCESS'. You will need to use the stateToken to continue the registration process.

1
{
2
  "state": "SUCCESS",
3
  "sessionToken": "MST.eyJraWQiOiJ3cTFCcFlDbyIsImFsZyI6IlJTMjU2In0...",
4
  "identity": {
5
    "id": "12432ed2-ef8b-6bf3-8f9n-94f3c4d0ef85",
6
    "identifiers": [
7
      {
8
        "email": "john@doe.com"
9
      }
10
    ],
11
    "revision": "1",
12
    "createdDate": "2023-07-19T11:14:08Z",
13
    "updatedDate": "2023-07-19T11:14:08Z",
14
    "connections": [
15
      {
16
        "authenticatorConnection": {
17
          "authenticatorConnectionId": "31ddd8fc-ea95-43ac-95c5-902497125b90",
18
          "reEnrollmentRequired": false
19
        }
20
      }
21
    ],
22
    "identityProfile": {
23
      "nickname": "Johnny Boy",
24
      "emails": [],
25
      "phones": [],
26
      "labels": [],
27
      "privacyStatus": "UNDEFINED",
28
      "customFields": []
29
    },
30
    "metadata": {
31
      "tags": []
32
    },
33
    "email": {
34
      "address": "john@doe.com",
35
      "isVerified": false
36
    },
37
    "status": {
38
      "name": "ACTIVE",
39
      "reasons": []
40
    }
41
  }
42
}

Log in a member

To log in an existing member using an email address and password the site visitor provides, call the Login V2 endpoint.

When calling the Login V2 endpoint, send the following parameters:

• loginId.email: Member's email address.
• password: Member's password.

1
curl --location 'https://www.wixapis.com/_api/iam/authentication/v2/login' \
2
--header 'authorization: <ACCESS_TOKEN>' \
3
--header 'content-type: application/json' \
4
--data '{
5
  "loginId":{
6
    "email": "john@doe.com"
7
  },
8
  "password": "verySecurePassword"
9
}'

The Login V2 endpoint initiates a member login and returns a response containing the state of the login operation and associated tokens.

The Login V2 endpoint's response contains the following:

• state: The current state of the login process. Use this state value to determine the next step in the login process.
• sessionToken: If the state value is 'SUCCESS', use the sessionToken to get the site members tokens.
• stateToken: If the state value is not 'SUCCESS'. You will need to use the stateToken to continue the login process.

1
{
2
  "state": "SUCCESS",
3
  "sessionToken": "MST.eyJraWQiOiJ3cTFCcFlDbyIsImFsZyI6IlJTMjU2In0...",
4
  "identity": {
5
    "id": "12432ed2-ef8b-6bf3-8f9n-94f3c4d0ef85",
6
    "identifiers": [
7
      {
8
        "email": "john@doe.com"
9
      }
10
    ],
11
    "revision": "1",
12
    "createdDate": "2023-07-19T11:14:08Z",
13
    "updatedDate": "2023-07-19T11:14:08Z",
14
    "connections": [
15
      {
16
        "authenticatorConnection": {
17
          "authenticatorConnectionId": "31ddd8fc-ea95-43ac-95c5-902497125b90",
18
          "reEnrollmentRequired": false
19
        }
20
      }
21
    ],
22
    "identityProfile": {
23
      "nickname": "Johnny Boy",
24
      "emails": [],
25
      "phones": [],
26
      "labels": [],
27
      "privacyStatus": "UNDEFINED",
28
      "customFields": []
29
    },
30
    "metadata": {
31
      "tags": []
32
    },
33
    "email": {
34
      "address": "john@doe.com",
35
      "isVerified": false
36
    },
37
    "status": {
38
      "name": "ACTIVE",
39
      "reasons": []
40
    }
41
  }
42
}

reCAPTCHA

You can use reCAPTCHA with both the Register V2 and Login V2 endpoints to protect your site or app from fraud and abuse.

Enable reCAPTCHA

Start by enabling reCAPTCHA on the Signup & Login Security page of your project dashboard.

Implement reCAPTCHA

Once reCAPTCHA is enabled for your project, use a 3rd-party library to implement the reCAPTCHA or choose to implement it yourself.

You can choose to always require reCAPTCHA verification or only require it for suspected bots.

• To always require reCAPTCHA verification, use a visible site key when loading the reCAPTCHA script.
• To only require reCAPTCHA verification for suspected bots, use an invisible site key when loading the reCAPTCHA script.

Use reCAPTCHA to register or login

After implementing a reCAPTCHA, call the Register V2 or Login V2 endpoint with the appropriate reCAPTCHA token returned to your reCAPTCHA implementation.

When always requiring reCAPTCHA verification, send the token using the captchaTokens.Recaptcha property.

1
curl --location 'https://www.wixapis.com/_api/iam/authentication/v2/login' \
2
--header 'authorization: <ACCESS_TOKEN>' \
3
--header 'content-type: application/json' \
4
--data '{
5
  "loginId":{
6
    "email": "john@doe.com"
7
  },
8
  "password": "verySecurePassword",
9
  "captchaTokens":{
10
    "Recaptcha": "<TOKEN>"
11
  }
12
}'

When only requiring reCAPTCHA verification for suspected bots, send the token using the captchaTokens.InvisibleRecaptcha property.

1
curl --location 'https://www.wixapis.com/_api/iam/authentication/v2/login' \
2
--header 'authorization: <ACCESS_TOKEN>' \
3
--header 'content-type: application/json' \
4
--data '{
5
  "loginId":{
6
    "email": "john@doe.com"
7
  },
8
  "password": "verySecurePassword",
9
  "captchaTokens":{
10
    "InvisibleRecaptcha": "<TOKEN>"
11
  }
12
}'

Login states

Both the Login V2 and Register V2 endpoints return a response containing the state of the login operation.

The state property of the response object indicates the login status. For example, if the above examples are successful, state is SUCCESS.

Make sure your code handles each of these state values:

• REQUIRE_EMAIL_VERIFICATION: Login requires email verification. This occurs when you try to register a new member with an email address belonging to an existing contact. In this case, you need to verify the email address.
• REQUIRE_OWNER_APPROVAL: After registration, this indicates site owner approval is required to complete registration for the new member. Handle this by informing the visitor that their membership is pending. Whenever the site owner approves their membership, the member can log in.
• SUCCESS: This indicates login was completed successfully. You can now get the site member's access and refresh tokens.

Verify email address

If the loginState property of the object returned by a call to Register V2 is REQUIRE_EMAIL_VERIFICATION, an email containing a verification code is sent automatically to the member's email address.

To complete the login process, use the Verify During Authentication endpoint.

When calling the Verify During Authentication endpoint, send the following parameters:

• code: The code received in the verification email.
• stateToken: The state token received in response to calling the Register V2 endpoint.

1
curl --location 'https://www.wixapis.com/verification-service/v1/auth/verify' \
2
--header 'authorization: <ACCESS_TOKEN>' \
3
--header 'content-type: application/json' \
4
--data '{
5
    "code": "123456",
6
    "stateToken": "AST.eyJraWQiOiJRUWpMeE1KaCIsImFsZyI6IlJTMjU2In0..."
7
}'

The Verify During Authentication endpoint's response contains the following:

• state: The current state of the login process. Use this state value to determine the next step in the login process.
• sessionToken: If the state value is 'SUCCESS', use the sessionToken to get the site members tokens.
• stateToken: If the state value is not 'SUCCESS'. You will need to use the stateToken to continue the login process.

Get the site member's access and refresh tokens

If the state property of the object returned by a call to Login V2, a call to Register V2, or a call to Verify During Authentication is SUCCESS, the member has been successfully logged in.

In this case, the response object contains a sessionToken property. Use the sessionToken to call the Redirect Session endpoint to get the logged-in member's access and refresh tokens. Before calling Redirect Session, you will need to prepare some information to be used in the call.

Prepare for a redirect session

Before you call the Redirect Session endpoint, you need to prepare the following:

• Your OAuth app client ID. You can retrieve this from the Headless Settings menu in the dashboard. If you haven't created an OAuth app yet, see Create an OAuth App for Visitors and Members to set one up.
• A PKCE code verifier and code challenge. These are used to prevent CSRF attacks and authorization code injection attacks.
• An OAuth2 state parameter used to mitigate CSRF attacks.

Get an authorization URL

Use the Redirect Session endpoint to get an authorization URL for the site member.

When calling the Redirect Session endpoint, send the following parameters, which include the data you prepared earlier:

• clientId: Your OAuth app client ID.
• codeChallenge: PKCE code challenge string.
• codeChallengeMethod: Use "S256".
• responseMode: Use "web_message".
• responseType: Use "code".
• scope: Use "offline_access".
• state: A state parameter.
• sessionToken: The session token received from a call to Login V2, a call to Register V2, or a call to Verify During Authentication.

1
curl --location 'https://www.wixapis.com/_api/redirects-api/v1/redirect-session' \
2
--header 'authorization: <ACCESS_TOKEN>' \
3
--header 'content-type: application/json' \
4
--data '{
5
  "auth": {
6
    "authRequest": {
7
      "clientId": "<CLIENT_ID>",
8
      "codeChallenge": "JNU5gZmEjgVL2eXfgSmUW3S2E202k2rkq4u3M_drdCY",
9
      "codeChallengeMethod": "S256",
10
      "responseMode": "web_message",
11
      "responseType": "code",
12
      "scope": "offline_access",
13
      "state": "Z4dy7JM2S7n35VnBhdMeOQyXQW7UkE2Q1afdPLL419o",
14
      "sessionToken": "MST.eyJraWQiOiJ3cTFCcFlDbyIsImFsZyI6IlJTMjU2In0..."
15
    }
16
  }
17
}'

The Redirect Session endpoint responds with:

• id: Redirect session ID.
• fullUrl: An authorization URL.

1
{
2
  "redirectSession": {
3
    "id": "83cab021-c3de-47b9-afa2-e93602e38b09",
4
    "fullUrl": "https://mysite.com/example/_api/oauth2/authorize?clientId=e345..."
5
  }
6
}

Authorize member

Once you have an authorization URL, you can use it to authorize a member before requesting their access and refresh tokens.

To perform an authorization:

1. Open the authorization URL in an iframe.
2. Listen for a postMessage from the iframe. It will include a state parameter and a code.
3. Check that the state value is the same as the state value you passed when getting the authorization URL.
4. Use the code to generate member tokens.

Generate member tokens

After performing authorization, you have a code that you can use to generate access and refresh tokens for the logged-in member. Generate new member tokens using the Token endpoint.

When calling the Token endpoint, send the following parameters:

• clientId: The client ID of the OAuth app your project is using.
• grantType: Set as "authorization_code" to get member tokens with an authorization code.
• code: The code you received in the authorization.
• codeVerifier: The code verifier you prepared for the redirect session.

1
curl --location 'https://www.wixapis.com/oauth2/token' \
2
--header 'content-type: application/json' \
3
--data '{
4
          "clientId": "<CLIENT_ID>",
5
          "grantType": "authorization_code",
6
          "code": "OLI79QEL",
7
          "codeVerifier": "bRGwKp1zdrSY_3A_GRvK2JI9Iq2MykDV5NjXk3tcQn4"
8
}'

The Token endpoint responds with:

• access_token: An access token used to authorize API calls.
• expires_in: The number of seconds before the access token expires. Access tokens expire after 4 hours (14,400 seconds).
• refresh_token: A refresh token used to get a new access token.

1
{
2
  "access_token": "OauthNG.JWS.eyJraWQiOi1JzdUpwSCIsImFsZyI6IkhTMjU2In0...",
3
  "token_type": "Bearer",
4
  "expires_in": 14400,
5
  "refresh_token": "JWS.eyJraWQiOiJ1SEJzdUpwSCIsImFsZyI6IkhTMjU2In0..."
6
}

Once you have tokens, you can use them to make authenticated calls to APIs on behalf of the current member.

Send a password-reset email

Call the Send Recovery Email endpoint to enable a member to reset their password.

When calling the Send Recovery Email endpoint, send the following parameters:

• email: Email address to send the recovery email to.
• redirect.url: The full URL to redirect the member to after they change their password. The redirect.url must be an allowed authorization redirect URI.
• redirect.clientId: The client ID of the OAuth app your project is using.

1
curl --location 'https://www.wixapis.com/_api/iam/recovery/v1/send-email' \
2
--header 'content-type: application/json' \
3
--header 'authorization: <ACCESS_TOKEN>' \
4
--data '{
5
    "email": "john@doe.com",
6
    "redirect": {
7
        "url": "https://mtsite.vercel.app",
8
        "clientId": "<CLIENT_ID>"
9
    }
10
}'

The Send Recovery Email endpoint responds with an empty response on success.

Log a member out

To log a site member out, take the following steps:

Get the member's logout URL

Use the Redirect Session endpoint to get a logout URL for the site member.

When calling the Redirect Session endpoint, send the following parameters:

• clientId: Your OAuth app client ID.
• postFlowUrl: Where the member will be redirected after logging out.

1
curl --location 'https://www.wixapis.com/_api/redirects-api/v1/redirect-session' \
2
--header 'content-type: application/json' \
3
--header 'authorization: <ACCESS_TOKEN>' \
4
--data '{
5
    "logout": {
6
        "clientId": "<CLIENT_ID>"
7
    },
8
    "callbacks": {
9
        "postFlowUrl": "https://mysite.com/"
10
    }
11
}'

Redirect to the logout URL

Redirect the browser to the returned fullUrl to log the site member out. The browser is automatically redirected back to the postFlowUrl that you passed to the Redirect Session endpoint.

Profile

The profile object contains the following properties: