Authentication

Forte provides built-in authentication for your project's users. You configure the authentication methods you want to support, and Forte handles user creation, session management, and security. Your application interacts with Forte's SDK to authenticate users and manage their sessions.

Forte currently supports Google OAuth, with phone number and email authentication coming soon.

Google OAuth

Google OAuth lets your users sign in with their Google accounts. Forte manages the entire OAuth flow. Configure your Google OAuth Client ID on your project, and Forte handles the rest: token verification, user creation, deduplication, CAPTCHAs, and session management.

How It Works

1. Your application renders Google's Sign-In button using your project's Google OAuth Client ID.
2. When a user completes the Google sign-in flow, Google returns a credential token to your application.
3. Your application sends the credential token to Forte's callback endpoint, along with a reCAPTCHA token if bot protection is enabled.
4. Forte verifies the token, creates or links the user, and returns a session token.

Example

import { GoogleLogin } from "@react-oauth/google";
import { ForteClient } from "@forteplatforms/sdk";
 
const forte = new ForteClient();
 
function LoginButton({ projectId }: { projectId: string }) {
  const handleSuccess = async (response) => {
    const csrfToken = crypto.randomUUID();
 
    // If reCAPTCHA is configured on your project, execute before calling the callback
    const recaptchaToken = await grecaptcha.execute("YOUR_RECAPTCHA_SITE_KEY", {
      action: "login",
    });
 
    const result = await forte.users.googleAuthLoginCallback({
      projectId,
      gCsrfToken: csrfToken,
      credential: response.credential,
      recaptchaToken, // optional — required if reCAPTCHA is configured
    });
 
    // result.userObject — the authenticated user
    // result.sessionToken.sessionToken — use for subsequent requests
    // result.sessionToken.expirationTime — token expiry (default: 365 days)
    console.log("Logged in as", result.userObject.fullName);
  };
 
  return <GoogleLogin onSuccess={handleSuccess} />;
}

Setup

Configure your Google OAuth Client ID on your project in the Console or via the CLI. Once configured, your application can use Google's Sign-In button and send the resulting credential to Forte.

User Creation and Linking

• If the user is signing in for the first time, Forte automatically creates a new user account with a verified Google contact method.
• If a user with the same email already exists in the project, Forte links the Google account to the existing user.
• Google OAuth contact methods are verified by default since Google has already verified the user's email.

Response

A successful authentication returns:

• The user object with the user's profile and contact methods
• A session token for authenticating subsequent requests
• The session token's expiration time (defaults to 365 days)

Bot Protection with reCAPTCHA

Forte supports Google reCAPTCHA v3 for automatic bot protection on your project's authentication endpoints. When configured, Forte validates a reCAPTCHA token on every sign-up and login request, rejecting requests that appear to come from bots or automated scripts.

reCAPTCHA v3 runs invisibly in the background — your users never see a challenge or checkbox. Instead, Google assigns a risk score to each request, and Forte rejects requests with scores that indicate automated or suspicious activity.

Why Use reCAPTCHA

• Prevent credential stuffing: Block automated login attempts that test stolen credentials against your application.
• Stop spam registrations: Prevent bots from creating fake user accounts in bulk.
• No user friction: reCAPTCHA v3 is invisible — legitimate users are never interrupted with challenges.

Setup

1. Go to the Google reCAPTCHA admin console and create a new site.
2. Select Score based (v3) as the reCAPTCHA type.
3. Add your application's domain(s) to the allowed domains list.
4. Google will provide two keys:
   • Site key — use this in your frontend to load the reCAPTCHA script and generate tokens.
   • Secret key — set this in your Forte project settings.
5. In the Forte Console, go to Project Settings and enter your reCAPTCHA v3 secret key.

Frontend Integration

Load the reCAPTCHA v3 script in your application and execute it before calling Forte's authentication endpoints. Pass the resulting token as recaptchaToken in your SDK calls.

// Load reCAPTCHA v3 script in your HTML:
// <script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
 
// Execute reCAPTCHA before authentication
const recaptchaToken = await grecaptcha.execute("YOUR_SITE_KEY", {
  action: "login", // use "login" or "signup" for Google OAuth
});
 
// Pass the token to the Forte SDK
const result = await forte.users.googleAuthLoginCallback({
  projectId,
  gCsrfToken: csrfToken,
  credential: response.credential,
  recaptchaToken,
});

Error Handling

If reCAPTCHA validation fails, Forte returns a 400 error with the error code RECAPTCHA_VALIDATION_FAILED. This can happen when:

• The reCAPTCHA token is missing or invalid.
• The request received a low risk score (indicating bot-like behavior).
• The token has expired (tokens are valid for a short time after generation).

reCAPTCHA Actions

When executing reCAPTCHA on your frontend, use these action names to match what Forte expects:

Phone Number Authentication

Phone number authentication will allow your users to sign in with their phone number using a password or a one-time passcode (OTP) sent via SMS. Forte's phone authentication is SDK-driven — you build your own sign-in UI and call Forte SDK functions to handle the authentication logic. This gives you full control over your UI/UX.

How It Will Work

1. Your application renders a custom sign-in form that collects the user's phone number.
2. Your application calls the Forte SDK to initiate the sign-in flow.
3. Forte sends a one-time passcode via SMS to the user's phone.
4. The user enters the passcode in your application, and your application submits it to Forte for verification.
5. On successful verification, Forte returns a session token.

Example Sign-In Component

Below is an example React component showing how phone authentication will work with the Forte SDK. Note the required SMS disclaimer.

PreviewCode

Phone number

By continuing, you agree to receive a one-time passcode via SMS.

Send Code

Email Authentication

Email authentication will allow your users to sign in with their email address using a password or a one-time passcode (OTP) sent via email. Like phone authentication, email authentication is SDK-driven — you build your own sign-in UI and call Forte SDK functions to handle the logic.

How It Will Work

1. Your application renders a custom sign-in form that collects the user's email address.
2. Your application calls the Forte SDK to initiate the sign-in flow.
3. Forte sends a one-time passcode via email to the user.
4. The user enters the passcode in your application, and your application submits it to Forte for verification.
5. On successful verification, Forte returns a session token.

Next Steps

• Learn about Contact Methods and how verification works
• Understand Sessions and token management