API Surfaces
Forte exposes two distinct HTTP API surfaces depending on where your code runs and which credential you hold. Understanding the split is the key to building a correct and secure integration.
| Client-side API | Server-side API | |
|---|---|---|
| SDK namespace | forte.users.* | forte.projects.* |
| Runs in | Browser or mobile app | Your backend service |
| Credential | End-user session cookie | FORTE_API_TOKEN |
| Acts as | The signed-in end user | The project owner |
Client-side API
The client-side API (forte.users.*) is designed to be called directly from a browser or mobile app. It authenticates with the end user's Forte-User-Session-Token cookie, which Forte sets automatically when a user logs in.
What you can do:
- Sign users in — Google OAuth, OTP via email or SMS
- Read and update the signed-in user's profile
- Manage the signed-in user's contact methods and verify them
- Create and list the signed-in user's payments
- Upload, share, and download content belonging to the signed-in user
- Renew or invalidate the user's session
Because the credential is the session cookie, the client-side API is scoped to the currently signed-in user. One user cannot read or modify another user's data.
Construct new ForteClient() with no arguments. The SDK relies on the Forte-User-Session-Token cookie, which is set automatically by Forte's authentication endpoints.
Server-side API
The server-side API (forte.projects.*) is designed to be called from your backend service. It authenticates with FORTE_API_TOKEN, which Forte injects automatically as an environment variable into every deployed service.
What you can do:
- Manage users as an admin — list, search, suspend, delete
- Read or set any user's contact methods without a verification code
- Create payments on behalf of any user in the project
- Manage services and website deployments
- Read request logs, metrics, and build history
- Send email or SMS to any user in the project
- Create and revoke project-scoped API keys
When your code runs inside a Forte Service, FORTE_API_TOKEN is injected as an environment variable. Construct new ForteClient() with no arguments and the SDK picks it up.
Credential Safety
FORTE_API_TOKEN is a server-side secret. If it appears in a browser bundle or client-side JavaScript, any visitor to your site can use it to act as the project owner — reading all user data, suspending accounts, sending arbitrary messages, and more.
FORTE_API_TOKEN belongs exclusively in server-side code or environment variables on your backend. It is intentionally not injected into Forte Websites for this reason.
The Forte-User-Session-Token cookie, by contrast, is designed to live in the browser. It is scoped to one user in one project and carries no admin powers.
Choosing the Right Surface
| I have… | Use |
|---|---|
| The session cookie (user just logged in) | Client-side API — forte.users.* |
FORTE_API_TOKEN in a server environment | Server-side API — forte.projects.* |
| A need to act as the signed-in user | Client-side API |
| A need to act on behalf of the project | Server-side API |
| A need to read another user's data | Server-side API |
If you're not sure: if the credential lives in a browser, use the client-side API. If the credential lives in a server environment variable, use the server-side API.
Common Pairings
Most resources expose both surfaces — a user-scoped path the end user calls themselves, and a project-owner path your backend calls on their behalf.
| Resource | Client-side (forte.users.*) | Server-side (forte.projects.*) |
|---|---|---|
| Payments | forte.users.createPayment | forte.projects.createPayment |
| Payment previews | forte.users.createPaymentPreview | forte.projects.createPaymentPreview |
| Contact methods | Self-service add, verify, delete | Admin add, override, mark verified without code |
| File content | Own content only | Any user's content |
See Creating Payments for a full worked example of both surfaces side-by-side.
SDK Shape
The same ForteClient class is used for both surfaces. The constructor differs:
Client-side (browser):
import { ForteClient } from "@forteplatforms/sdk";
// No credentials — relies on the Forte-User-Session-Token cookie
const forte = new ForteClient();
// Calls forte.users.* on behalf of the signed-in user
const preview = await forte.users.createPaymentPreview({ projectId, ... });Server-side (inside a Forte Service):
import { ForteClient } from "@forteplatforms/sdk";
// FORTE_API_TOKEN is injected automatically — no arguments needed
const forte = new ForteClient();
// Calls forte.projects.* as the project owner
const { items } = await forte.projects.listUsers({ projectId });Server-side (local dev or external system):
const forte = new ForteClient({ apiToken: process.env.FORTE_API_TOKEN });