SDKs

Forte provides SDKs for TypeScript, Java, and Python. You can use these to interact with Forte's APIs either from your server or web frontend.

Installation

See the SDK repository for installation instructions for TypeScript, Java, and Python.

Automatic credential loading

When your code runs inside a Forte Service, the SDK automatically reads credentials from the environment variables that Forte injects at runtime:

VariableDescription
FORTE_PROJECT_IDThe project this service belongs to
FORTE_SERVICE_IDThis service's ID
FORTE_API_TOKENA Bearer token scoped to this project

Create a client with no arguments. The SDK reads the injected credentials.

typescript
import { ForteClient } from "@forteplatforms/sdk";
 
// Credentials are loaded automatically from the environment
const forte = new ForteClient();

Common use cases

Retrieve the authenticated user

Every request to your service includes an X-Forte-User-Id header with the authenticated user's ID. Use the SDK to fetch the full user profile:

typescript
import { ForteClient } from "@forteplatforms/sdk";
 
const forte = new ForteClient();
const projectId = process.env.FORTE_PROJECT_ID!;
 
app.get("/profile", async (req, res) => {
  const userId = req.headers["x-forte-user-id"] as string;
  const user = await forte.projects.getUser({ userId, projectId });
 
  res.json({
    name: user.fullName,
    email: user.contactMethods.find((c) => c.type === "EMAIL")?.value,
  });
});

List users in the project

Query all users in your project with pagination:

typescript
const { items, nextPageToken } = await forte.projects.listUsers({ projectId });

Store custom attributes on a user

Attach arbitrary key-value metadata to users: useful for subscription tiers, feature flags, or app-specific preferences:

typescript
const userId = req.headers["x-forte-user-id"] as string;
 
await forte.projects.putUserCustomAttributes({
  userId,
  projectId,
  requestBody: {
    plan: "pro",
    referral_source: "google",
    onboarding_completed: "true",
  },
});
 
// Read them back
const user = await forte.projects.getUser({ userId, projectId });
console.log(user.customMetadataAttributes);
// { plan: 'pro', referral_source: 'google', onboarding_completed: 'true' }
Replacement semantics

Each call replaces all custom attributes on the user. To update a single field, read the user first, merge, then write back. Keys must be 1–64 characters (letters, numbers, underscores, hyphens). Values are strings.

Using the SDK outside Forte

The SDK runs in any environment. How you construct the client depends on which API surface you're targeting.

Client-side (browser or mobile app)

To call forte.users.* from a browser, construct the client with no arguments. The Forte-User-Session-Token cookie authenticates each call; Forte sets it automatically when the user logs in. See Authentication for the login flows that establish the cookie.

typescript
import { ForteClient } from "@forteplatforms/sdk";
 
// No credentials: the Forte-User-Session-Token cookie is sent automatically
const forte = new ForteClient();
Never pass apiToken to a browser

FORTE_API_TOKEN is a server-side secret. Do not pass it to the ForteClient constructor in client-side JavaScript: use the preceding no-argument form instead. See API surfaces for details.

First-party cookies via /_forte

A browser stores a cookie for the domain that set it, and only sends it back to that domain. When your frontend calls forte.users.* against the Forte API, Forte sets the Forte-User-Session-Token cookie on Forte's domain. The browser then never sends that cookie to your service, so Forte can't tell which user is calling and rejects requests to your service with 401 NO_AUTHORIZATION_CREDENTIAL.

Every service reserves the path prefix /_forte on its own domain. Forte handles requests under it itself, before they reach your code. Point the SDK there and Forte sets the cookie on your service's domain, so the browser sends it with every later request to your service.

typescript
import { ForteClient } from "@forteplatforms/sdk";
 
// forte.users.* calls go to https://api.example.com/_forte/..., so the
// session cookie is set on api.example.com, the domain your service runs on.
const forte = new ForteClient({
  baseUrl: "https://api.example.com/_forte",
});
 
await forte.users.completeOtpLogin({
  projectId,
  pendingLoginId,
  completeOtpLoginRequest: { code },
});
 
// Later requests to your service carry the cookie, and Forte adds the
// X-Forte-User-Id header before forwarding them to your code.
await fetch("https://api.example.com/orders", { credentials: "include" });

Nothing else about the SDK changes: every forte.users.* call works exactly as it does against the Forte API directly. If your frontend is served from the service's own domain, baseUrl: "/_forte" works too.

When you need /_forte

Use /_forte when both of these are true:

  • Your browser code calls forte.users.* itself to log users in, renew sessions, or log out.
  • Requests to your service authenticate with the session cookie, not an Authorization header.

You don't need /_forte when:

  • Your client sends a bearer token. Login responses include the session token (sessionToken.sessionToken). If your client keeps it and sends Authorization: Bearer <token> on each request to your service, the cookie's domain doesn't matter. This is the usual setup for mobile apps, desktop apps, and command-line tools, and it works in the browser too.
  • Your own backend handles login. If a route in your service calls forte.users.* with the user's credentials and sets the Forte-User-Session-Token cookie on its own response, the cookie is already on your domain.
  • The code is server-side. Calls made with FORTE_API_TOKEN go directly to the Forte API and never involve the session cookie.

Pick one method per client. If a request carries both a cookie and a bearer token and they don't match, Forte rejects it with 401 MISMATCHED_AUTH_TOKENS.

Frontends on another domain

The cookie belongs to the exact host that served the /_forte request, and it's sent only on same-site requests. If your frontend runs on app.example.com and your service on api.example.com:

  • Call /_forte on api.example.com, the host your frontend sends API requests to.
  • Send requests with credentials: "include", and have your service's CORS handler allow credentials from https://app.example.com.

If your frontend is on a different site entirely, such as example.vercel.app calling api.example.com, the browser won't send the cookie. Use bearer tokens instead.

Websites don't have a /_forte path, because website traffic doesn't pass through a service. A website frontend can call /_forte on a connected service's domain, as long as both are on the same site.

What's reachable through /_forte

Only end-user routes: the client-side API: are reachable through the prefix. Server-side calls need FORTE_API_TOKEN and should still go directly to the Forte API. The /_forte path is reserved on every service, so avoid defining your own routes under it.

Not counted as service traffic

Requests sent through /_forte are handled by Forte before they reach your service, so they don't appear in your service's request logs, latency metrics, or request counts.

Server-side (local dev or outside Forte)

For server-side code running outside a Forte Service (local development, an external system, or CI scripts), pass FORTE_API_TOKEN explicitly:

typescript
const forte = new ForteClient({
  apiToken: process.env.FORTE_API_TOKEN,
});

Or set FORTE_API_TOKEN as an environment variable and call new ForteClient() with no arguments: the SDK reads it automatically.

bash
export FORTE_API_TOKEN="your-api-token"

Client-side recipes

The following examples use forte.users.*: the client-side API. These run in a browser where the Forte-User-Session-Token cookie is already set after login.

Compute a payment total

typescript
const forte = new ForteClient(); // session cookie is set automatically
 
const preview = await forte.users.createPaymentPreview({
  projectId,
  createPaymentPreviewRequest: {
    currency: "usd",
    lineItems: [
      { description: "Pro plan", unitAmountCents: 2500, quantity: 1, taxCode: "txcd_10000000" },
    ],
  },
});
 
console.log(`Total: $${preview.amountCents / 100}`);

Renew a session token

Session renewal lives on the Sessions page, which shows renewSessionToken in TypeScript, Java, and Python.

Next steps

Search

Search your resources, console pages, and documentation