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:
| Variable | Description |
|---|---|
FORTE_PROJECT_ID | The project this service belongs to |
FORTE_SERVICE_ID | This service's ID |
FORTE_API_TOKEN | A Bearer token scoped to this project |
Create a client with no arguments. The SDK reads the injected credentials.
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:
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:
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:
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' }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.
import { ForteClient } from "@forteplatforms/sdk";
// No credentials: the Forte-User-Session-Token cookie is sent automatically
const forte = new ForteClient();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.
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
Authorizationheader.
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 sendsAuthorization: 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 theForte-User-Session-Tokencookie on its own response, the cookie is already on your domain. - The code is server-side. Calls made with
FORTE_API_TOKENgo 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
/_forteonapi.example.com, the host your frontend sends API requests to. - Send requests with
credentials: "include", and have your service's CORS handler allow credentials fromhttps://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.
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.
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:
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
Session renewal lives on the Sessions page, which shows renewSessionToken in TypeScript, Java, and Python.
Next steps
- Understand API surfaces: client-side versus server-side, and credential safety
- Learn how service tokens are injected into your services
- Set up authentication for your project's users