SDKs

Forte provides runtime SDKs for TypeScript, Java, and Python. These SDKs give your services a simple interface to interact with the Forte API — managing users, reading project data, and more — without dealing with authentication manually.

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:

FORTE_API_TOKEN is scoped to the service's project and injected automatically — just import the SDK and start using it.

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:

Server-side (API key):

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:

Server-side (API key):

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:

Server-side (API key):

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' }

Using Outside Forte

The SDK can be used 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. Authentication is handled by the Forte-User-Session-Token cookie, which Forte sets automatically when the user logs in. See Authentication for the login flows that establish the cookie.

import { ForteClient } from "@forteplatforms/sdk";
 
// No credentials — the Forte-User-Session-Token cookie is sent automatically
const forte = new ForteClient();

First-party cookies via /_forte

When your frontend calls forte.users.* directly against the Forte API, the Forte-User-Session-Token cookie is set on Forte's domain — meaning from your frontend it's a third-party cookie. Modern browsers block third-party cookies by default and silently sign your users out on cross-site requests.

Every account-owned service reserves a path prefix at /_forte. Point the SDK there and the cookie is set on your own domain instead — first-party, same origin as your frontend, never blocked.

import { ForteClient } from "@forteplatforms/sdk";
 
// Point the SDK at your own service domain. `forte.users.*` calls travel
// through `/_forte` and Forte handles them — but the session cookie is now
// scoped to myapi.com, where your frontend lives.
const forte = new ForteClient({
  baseUrl: "https://myapi.com/_forte",
});
 
const result = await forte.users.renewSessionToken({
  projectId,
  authorization: `Bearer ${currentSessionToken}`,
});

Nothing else about the SDK changes — every forte.users.* call works exactly as it does against the Forte API directly.

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 the project API key explicitly:

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.

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

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

const forte = new ForteClient();
 
const result = await forte.users.renewSessionToken({
  projectId,
  authorization: `Bearer ${currentSessionToken}`,
  renewalDurationSeconds: 2592000, // 30 days
});
 
// result.sessionToken — the renewed token

Next Steps

• Understand API Surfaces — client-side vs. server-side and credential safety
• Learn how Service Tokens are injected into your services
• Set up Authentication for your project's users