Contact Methods

Users can have multiple contact methods associated with their account. A contact method is an email address, phone number, or Google account that the user has linked. By default, only users with at least one verified contact method can make calls to your Services hosted in Forte. Unauthenticated and unverified calls will be rejected with an HTTP 401/403 error.

To learn more about user authentication, see Authentication and Sessions.

Types

*When Google indicates that the user's email is verified. In rare cases, OAuth accounts may require manual verification.

Verification Flow

For email and phone contact methods, Forte sends a 6-digit verification code to the user:

1. The user adds a new contact method (email or phone) to their account.
2. Forte sends a 6-digit verification code to the contact method.
3. The user enters the code in your application.
4. Your application submits the code to Forte's verification endpoint.

Verification rules:

• Codes expire after 10 minutes
• Resending a code requires a 60-second cooldown between attempts
• Users cannot delete their last verified contact method

Unverified Contact Methods

An unverified email or phone number is reserved within the project as soon as the user adds it — a second user in the same project cannot register or add the same identifier while the first user's verification is still in progress. Attempting to do so returns USER_ALREADY_EXISTS (HTTP 409).

This reservation is time-bound, not permanent. Once the original verification code expires (10 minutes after it was last sent) without being entered, the unverified contact method becomes stale and is eligible to be reclaimed.

What "stale" means

A contact method is stale when both:

• It has never been verified, and
• More than 10 minutes have passed since the last verification code was issued (i.e. the code window has elapsed and the contact method's owner did not complete verification or request a new code).

A verified contact method is never stale and is never reclaimed — it permanently owns that identifier within the project.

Reclaim behavior

When a new user attempts to register — or an existing user attempts to add a contact method — that matches a stale unverified entry on another user, Forte transfers the identifier to the new caller:

1. The stale entry is removed from the original user.
2. If that was the original user's only contact method, the original user is removed from the project (they had no verified way to authenticate, so the account was effectively unrecoverable). Any session token that was issued to that user during their incomplete registration is invalidated at the same moment — see Sessions → Automatic Invalidation.
3. The new caller's request proceeds as if the identifier had been free. A fresh verification code is sent to the new caller.
4. An audit log entry of type CONTACT_METHOD_DISPLACED is recorded against the original user, naming the displaced contactMethodId. See Administration for retrieving user action logs.

When the new caller eventually verifies the reclaimed identifier (their first verified contact method on the new account), every other outstanding session for that account is also invalidated. This protects the account against any stale sessions that may have existed from prior unverified registration attempts on the same identifier — see Sessions → Automatic Invalidation.

When the request is still rejected

You will still see USER_ALREADY_EXISTS (HTTP 409) when:

• Another user in the project owns the identifier as a verified contact method.
• Another user in the project is mid-verification — they added the identifier within the last 10 minutes and the code has not yet expired.

In both cases the new caller should treat the identifier as taken. The first case requires the original owner to remove the contact method themselves; the second resolves automatically once the verification window elapses.

SDK Functions

The Forte SDK provides utility functions for managing contact method verification:

• resendOTP — Resend a one-time passcode to the user's phone number or email address. Subject to a 60-second cooldown between attempts.
• resendVerificationCode — Resend a verification code for a contact method that has not yet been verified. Also subject to a 60-second cooldown.

Next Steps

• Set up Authentication methods for your users
• Learn about Sessions and token management
• Administrate your users from the Forte console