FinBaze for Platforms

Start

You will create a company and a user, mint an embed session on your server and show the tax calendar in a React page. All steps use the sandbox.

1. Get test keys#

In the developer portal open Keys and create a secret key and copy the publishable key. Test keys start with fb_sk_test_ and fb_pk_test_. The secret key stays on your server.

2. Allow your origin#

Under Embedding → Allowed origins add the origin of the page that will show the components, for example http://localhost:3000. Components refuse to load anywhere else.

3. Get a server token#

Exchange the secret key for a short-lived token:

curl https://sandbox.api.platform.finbaze.com/v2/oauth2/token \
  -H 'content-type: application/json' \
  -d '{"grant_type":"client_credentials","client_secret":"fb_sk_test_…"}'

Send the access_token as Authorization: Bearer … on every GraphQL request to https://sandbox.api.platform.finbaze.com/graphql.

4. Create a company#

mutation {
  createPlatformCompany(input: {
    externalId: "acme-1"
    registrationCountry: NL
    registrationNumber: "12345678"
  }) {
    company { id name }
    created
  }
}

externalId is your id; calling this again with the same id returns the same company. The returned company.id is the profile id the rest of the API uses.

5. Create a user and give them access#

mutation {
  upsertPlatformUser(input: { externalUserId: "user-42", firstName: "Sam", lastName: "Jansen" }) { id }
  setPlatformUserAccess(input: { externalUserId: "user-42", profileId: "<company id>", role: admin }) { role }
}

Users are hidden: they never get a FinBaze login or email. See platforms and companies.

6. Add an endpoint that creates embed sessions#

Your page cannot hold the secret key, so it asks your backend. The backend authenticates your user and creates a session:

app.post("/finbaze/session", requireLogin, async (req, res) => {
  const { data } = await finbaze(`
    mutation($input: CreateEmbedSessionInput!) {
      createEmbedSession(input: $input) { clientSecret }
    }`, {
    input: {
      companyId: req.user.finbazeCompanyId,
      user: { externalUserId: req.user.id },
      components: { taxCalendar: { enabled: true } },
      previousSessionId: req.body.previousSessionId,
    },
  });
  res.json({ clientSecret: data.createEmbedSession.clientSecret });
});

Each client secret works once and for 15 minutes. Do not cache it. Pass previousSessionId through; it links refreshes into one chain.

7. Install the SDK#

npm install @finbaze/embed-react

8. Show a component#

import { FinBazeProvider, FinBazeTaxCalendar } from "@finbaze/embed-react";

export function Taxes() {
  return (
    <FinBazeProvider
      publishableKey="fb_pk_test_…"
      fetchClientSecret={async ({ previousSessionId }) => {
        const res = await fetch("/finbaze/session", {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({ previousSessionId }),
        });
        return (await res.json()).clientSecret;
      }}
    >
      <FinBazeTaxCalendar onError={(e) => console.error(e)} />
    </FinBazeProvider>
  );
}

The SDK calls fetchClientSecret again before the token expires, so the component keeps working.

9. Match your look#

<FinBazeProvider appearance={{ theme: "auto", variables: { colorPrimary: "#0a7d5a", borderRadius: "10px" } }} …>

See the appearance reference.

10. Next steps#