Handle Members with a Custom Login Page Using the REST API

This article explains how to implement a custom login page using the JavaScript SDK.

Step 1 | 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.

Step 2 | Sign up a new member

To register a new member using an email address and password the site visitor provides, call Register V 2, specifying the following parameters:

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

Include an authorization header with the temporary visitor access token. Learn how to generate a temporary visitor access token.

Register V 2 initiates a new member registration and returns a response containing the state of the registration operation and associated tokens. Its 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.

Step 3 | Log in a member

To log in an existing member using an email address and password the site visitor provides, call Login V 2, specifying the following parameters:

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

Include an authorization header with the temporary visitor access token generated during the prerequisites.

Login V 2 initiates a member login and returns a response containing the state of the login operation and associated tokens. Its 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.

Step 4 | Handle login states

Both Login V 2 and Register V 2 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.

Step 5 | Verify email address

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

To complete the login process, call Verify During Authenticationspecifying the following parameters:

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

Verify During Authentication'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.

Step 6 | Get the site member's access and refresh tokens

If the state property of the object returned by a call to Login V 2, a call to Register V 2, 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 Create Redirect Session to get the logged-in member's access and refresh tokens. Before calling Create Redirect Session, you will need to prepare some information to be used in the call.

Step 7 | Prepare for a redirect session

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

• The Client ID of your OAuth app. You can find this value in your Headless Settings. 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.

Step 8 | Get an authorization URL

Call Create Redirect Session to get an authorization URL for the site member. Specify the following parameters, which include the data you prepared earlier:

• clientId: The Client ID of your OAuth app, which can be found in your project's Headless Settings.
• 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 V 2, a call to Register V 2, or a call to Verify During Authentication.

Create Redirect Session responds with:

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

Step 9 | 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 Create Access Token.

When calling Create Access Token, specify the following parameters:

• clientId: The Client ID of your OAuth app, which can be found in your project's Headless Settings.
• 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.

Create Access Token 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.

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

Step 10 | Send a password-reset email

To enable a member to reset their password, call Send Recovery Email, specifying 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 your OAuth app, which can be found in your project's Headless Settings.

Send Recovery Email responds with an empty response on success.

Logging out a member

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

1. Get the member's logout URL

Use Create Redirect Session to get a logout URL for the site member specifying the following parameters:

• clientId: The Client ID of your OAuth app, which can be found in your project's Headless Settings.
• postFlowUrl: Where the member will be redirected after logging out.

2. 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 specified when calling Create Redirect Session.

Profile

The profile object contains the following properties: