npm install @finbaze/platform-sdk

import Finbaze from "@finbaze/platform-sdk";

const finbaze = new Finbaze({ secretKey: process.env.FINBAZE_SECRET_KEY }); // fb_sk_test_… uses the sandbox

Create a company, a user and an embed session#

const company = await finbaze.platform.companies.create({ externalId: "acme-1", registrationCountry: "NL", registrationNumber: "12345678" });
const user = await finbaze.platform.users.upsert({ externalUserId: "user-42", firstName: "Sam", lastName: "Jansen" });
await finbaze.platform.users.setAccess({ userId: user.id, companyId: company.id, role: "admin" });

const session = await finbaze.platform.embedSessions.create({
  company: company.id,
  user: { id: user.id },
  components: { taxCalendar: { enabled: true } },
  previousSessionId, // from the browser SDK's fetchClientSecret
});
return { clientSecret: session.clientSecret };

Calls that write take { idempotencyKey }; the SDK retries network errors, 429 and 503, and generates a key for a mutation it retries.

Act as a user#

const asUser = finbaze.asUser({ externalUserId: "user-42" }, { companyIds: [company.id] });
await asUser.companies.taxCalendar.retrieve(company.id, { year: 2026 });
await asUser.companies.transactions.list(company.id, { processed: false });

Webhooks#

const event = await finbaze.webhooks.constructEvent(rawBody, req.header("x-finbaze-signature"), process.env.FINBAZE_WEBHOOK_SECRET);

Pass the body exactly as received. Failures throw FinbazeSignatureVerificationError.

What is in it#

platform (companies, users, userTokens, embedSessions, features, usage, origins, and for the control surfaces messages, providers, paymentRequests, paymentLinks, taxReservation, stepUp, policies, extensions, documentLayouts, documentTemplates, documentRendering, documentFonts, customDomains), companies (bankAccounts, transactions, documents, taxCalendar, actionItems, filings, plus the invoice, relation and project resources), webhooks, Finbaze.oauth(...) for marketplace apps, and graphql for anything else. @finbaze/platform-sdk/operations adds a typed function for each of about 850 operations (a separate entry point, since it is large). Errors carry code, param and requestId; see errors.

Control surfaces#

import { Finbaze, isControlEvent, isMessageEvent } from "@finbaze/platform-sdk";

const event = await finbaze.webhooks.constructPlatformEvent(rawBody, signature, secret);
if (isMessageEvent(event)) {
  // event.data.object.type narrows event.data.object.data
} else if (isControlEvent(event) && event.type === "payment_link.requested") {
  await finbaze.platform.paymentLinks.provide({
    requestId: event.data.object.paymentLinkRequest.id,
    url: "https://pay.example.com/i/42",
  });
}

See messages, delegated actions, policies and extensions and documents and rendering.

Without the SDK#

const BASE = "https://sandbox.api.platform.finbaze.com";
let token: { value: string; expiresAt: number } | null = null;

async function serverToken() {
  if (token && token.expiresAt > Date.now() + 30_000) return token.value;
  const res = await fetch(`${BASE}/v2/oauth2/token`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ grant_type: "client_credentials", client_secret: process.env.FINBAZE_SECRET_KEY }),
  });
  const body = await res.json();
  token = { value: body.access_token, expiresAt: Date.now() + body.expires_in * 1000 };
  return token.value;
}

export async function finbaze<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
  const res = await fetch(`${BASE}/graphql`, {
    method: "POST",
    headers: { "content-type": "application/json", authorization: `Bearer ${await serverToken()}` },
    body: JSON.stringify({ query, variables }),
  });
  const body = await res.json();
  if (body.errors?.length) throw Object.assign(new Error(body.errors[0].message), { code: body.errors[0].extensions?.code });
  return body.data;
}

The GraphQL reference lists every operation with the scope it needs.

Other languages#

The same resources exist in Python, PHP and Kotlin and Java; server SDK snippets shows each call in all five languages.