Sessions

After a user authenticates, Forte issues a session token that your application uses to authenticate subsequent API requests.

Using Session Tokens

You can authenticate requests in two ways:

• Cookie: The Forte-User-Session-Token cookie is set automatically on authentication responses. Browsers send it automatically — this is the recommended approach 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 are not automatic.

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

Forte session tokens are cryptographically signed and cannot be decoded or inspected. They are opaque strings that can only be validated or invalidated by Forte.

Token Lifetime

• Session tokens default to 365 days expiration
• Tokens can be renewed with a configurable duration
• Tokens can be explicitly invalidated by calling the logout endpoint

Renewal

Session tokens can be renewed before they expire. When you renew a token, Forte issues a new token with a fresh expiration time. The default renewal duration is 1 year, but this can be customized 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

Automatic Invalidation

In addition to 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 a previously-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 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.

Subsequent verifications — adding and verifying additional 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 several devices.

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.

Logout

Calling the logout endpoint invalidates the current session token immediately. The token can no longer be used to 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