Sessions

After a user signs in, Forte issues a session token. Your app uses this token to authenticate later requests.

Use a session token

You can authenticate requests in two ways:

• Cookie: Authentication responses set the Forte-User-Session-Token cookie. Browsers send it automatically. Use this method for web apps.
• Session-token Bearer header: Include the user session token in the Authorization header as Bearer {sessionToken}. Use this in mobile apps or other non-browser clients where cookies aren't automatic.

If you provide both, they must be identical to avoid a mismatched token error.

Forte session tokens are cryptographically signed opaque strings. You cannot decode or inspect them, and only Forte can verify or invalidate them.

Set the token lifetime

• Session tokens expire after 365 days by default
• You can renew tokens with a configurable duration
• Calling the logout endpoint invalidates a token

Pending MFA tokens

If your project enables multi-factor authentication, a first-factor sign-in may return a pending session token instead of a full one — signaled by an mfaStatus of CHALLENGE_REQUIRED or ENROLLMENT_REQUIRED on the login response. A pending token is short-lived (about 10 minutes) and authenticates only the endpoints needed to finish signing in: the MFA challenge, verify, and list-methods endpoints, plus logout. A pending token in the ENROLLMENT_REQUIRED state additionally reaches the enrollment endpoints — create, activate, and backup-code generation — so a user the project forces into MFA can set up a factor first. A CHALLENGE_REQUIRED pending token cannot enroll — the user already has a usable factor and must complete it. Every other request — including any request to your deployed app — rejects a pending token with 401 MFA_REQUIRED.

A pending token cannot be renewed. A pending login response also omits the userObject — the user's data stays behind the second factor until it's verified. Once the user satisfies their second factor with verifyMfa, Forte deletes the pending token, issues a full session token in its place, and updates the Forte-User-Session-Token cookie on that response. A full session token always reports an mfaStatus of SATISFIED (or omits it entirely).

Renew a session

You can renew a session token before it expires. Forte then issues a new token with a fresh expiry. The default renewal duration is 1 year, but you can customize it per request.

const result = await forte.users.renewSessionToken({
  projectId,
  authorization: `Bearer ${currentSessionToken}`,
  renewalDurationSeconds: 2592000, // 30 days (optional, defaults to 1 year)
});
 
// result.sessionToken — the new token
// result.expirationTime — new expiry

Understand automatic invalidation

Beyond explicit logout and TTL expiry, Forte invalidates session tokens automatically in two situations. Both close a narrow takeover window that exists before a user has verified any contact method — during that window, the session belongs to whoever called register, not necessarily to the rightful owner of the email or phone number on file.

First-time contact-method verification

When a user verifies their first contact method on an unverified account, every other outstanding session token for that user is invalidated. The token used to make the verification call is preserved — the verifying caller stays signed in. This first verification can also happen as a side effect of signing in: completing an OTP login or a password reset on an unverified contact (only possible while the account has no verified owner) verifies it and triggers the same invalidation. In that case the session preserved is the one that login or reset just issued.

This handles the case where two parties briefly held sessions for the same unverified account (for example, someone registered with another person's email, the email's owner later reclaimed the identifier, and both parties had session tokens scoped to the same record). Once the account is claimed by verification, only the verifying caller's session can continue.

Later verifications — adding and verifying more contact methods on an already-claimed account — do not trigger this invalidation. By that point the account has a real owner and they may legitimately be signed in from more than one device.

Reclaim of a stale contact method

When a stale unverified contact method is reclaimed by a new caller and the displaced user had no other contact methods, the displaced user record is removed. Any session token issued to that displaced user during their incomplete registration is invalidated at the same time, so an unverified session cannot continue to authenticate against the project after the user it referred to has been removed.

If the displaced user had other contact methods and only one entry was reclaimed, their session tokens remain valid — the underlying user account is intact.

Log out

Calling the logout endpoint invalidates the current session token immediately. The token can no longer authenticate requests after logout.

await forte.users.logout({
  projectId,
  authorization: `Bearer ${sessionToken}`,
});

Next steps

• Learn about Contact methods and how verification works
• Set up Authentication methods for your users
• Manage users with Administration tools