FinBaze for Platforms

Guides

The changelog lists everything. This page lists what asks something of your code, newest first, and how to read versions. The current versions are on Versions.

How versions work today#

  • API version. Every webhook delivery carries apiVersion in its body and X-FinBaze-Api-Version in its headers. Until a second version exists, every endpoint gets the current one; pinning a version per platform is not available yet. Branch on fields you know, ignore fields you do not.
  • GraphQL. One schema. A change to it needs an entry in the changelog. Fields and operations are added; read the changelog before you rely on removed or renamed ones.
  • Browser SDKs (@finbaze/embed-js, @finbaze/embed-react) are 0.x and follow semver. The controller loads from FinBaze's origin, so a component is always current; the SDK is the thin part that mounts it. Pin the SDK version in your lockfile and update it deliberately.
  • Server SDK (@finbaze/platform-sdk) is 1.0 and not on npm yet; the plain GraphQL calls on its page do the same work.
  • Mobile SDKs are planned as 0.x betas with Wave 6.2; they will follow semver, and the protocol between the SDK and the embed app carries a version so that old SDK versions keep working for at least 12 months. See Mobile.

What asks something of you#

A platform company's returns are filed only with its admin's authorisation. A submit without it fails with TAX_AUTHORISATION_REQUIRED. What to do: mount tax-authorisation or onboarding where the company's admin sets up filing, and hide your own submit button for companies without consent (read taxAuthorisationStatus). See Filing consent.

Webhook secrets and rotation#

When you rotate a secret (rotatePlatformWebhookSecret), both secrets sign for the period you choose, so the header carries two v1 values. What to do: make your verifier accept a list of secrets and any matching v1 (receivers in three languages), deploy the new secret, then let the old one expire.

Sandbox resets#

Companies that are not marked preserve are removed in a nightly reset when you switch it on. What to do: seed fixtures with stable externalIds (seedTestCompany does) and make your tests idempotent. See Sandbox reset.

Client secrets#

A secret is single use and valid for 15 minutes. If you cached one, you will see EMBED_SECRET_USED. What to do: return a new secret from every fetchClientSecret call.

Planned: stricter operation checks for embed and headless tokens#

Embed and headless tokens already run only allowlisted operations. The check is moving to identify operations by the hash of their normalised document, rolled out in the sandbox first in a mode that only logs, then enforced after the gallery and the sample apps pass for a week. What to do: nothing, as long as you use FinBaze's components and hooks. If you run your own documents with a headless token, they will be refused once the check is enforced: use the server API for those. The changelog announces each step.

When something does not work after an upgrade#

  1. Read the error codes for the code you see.
  2. Check the changelog entry of the release.
  3. Send the X-Request-Id of the failing request to support.