Skip to content

How embedded white label works Finland ​

Draft

A first technical overview, drawn from the white label and security guides of the current developer site. The step-by-step guides are now on this site (see the end of the page).

Embedded white label puts Salaxy's payroll UI — a single-page application — in an iframe inside your product. You keep your product, your navigation and your users' sign-in; Salaxy runs the payroll. It has been used in production since 2018, on desktop and mobile browsers and in mobile apps through web views.

What runs where ​

White label architectureYour web app shows the Salaxy payroll UI in an iframe. Your backend signs the user in and gets a Salaxy access token with a signed JWT. The iframe loads the payroll application from embed.palkkaus.fi with the token in the URL hash and calls the Salaxy API.YOUR PRODUCTSALAXYBrowser — your web appYour header, menu and footeriframe — Salaxy payroll UIembed.palkkaus.fi/embedded.html?lang=fi&skin=your-brand#access_token=… (first load only)Navigate by changing only the hash:#/payrollNever change anything before the #Your backendYour own user loginSSO: signs a JWT with the certificateyou created in SalaxyOptional: REST API integrationsembed.palkkaus.fiServes the payroll application and your designTest, demo and production hostsSalaxy API and payroll engineCalculations, payments, Incomes Register,pensions, accounting dataSalaxy token endpointChecks the signed JWT, issues a short-liveduser access token — no refresh tokensSalaxy REST API (optional)Account creation, payment channel, accounting1234567
Purple: provided and run by Salaxy. Grey: built and run by you. Dashed: optional.
  1. The user signs in to your product — with your own login. Your users do not sign in to Salaxy separately.
  2. Your backend asks Salaxy for a token for that user. It signs a short-lived JWT with the certificate you created in Salaxy and posts it to the Salaxy token endpoint — the impersonation flow for single sign-on. Salaxy only accepts it if the user's account has authorised your product.
  3. Salaxy returns a short-lived user access token. There are no refresh tokens: when it expires, repeat step 2.
  4. Your page puts the token into the iframe's URL, in the hash (#access_token=…), on the first load only.
  5. The iframe loads the payroll application and your design from embed.palkkaus.fi (test-embed. and demo-embed. for testing — see Environments). The design is selected with the skin URL parameter or, without it, by the company's service model.
  6. The payroll UI calls the Salaxy API with the token. Payroll logic, payments, Incomes Register and pension reporting all happen on Salaxy's side.
  7. Optional: your backend uses the REST API for what happens outside the UI — creating customer accounts from your system, taking payments through your own payment channel, fetching accounting data.

Navigation is client-side routing inside the iframe. Either embed embedded-horizontal.html, which has Salaxy's own menu, or embed embedded.html and drive it from your own menu by changing only the part after # (for example #/payroll). Changing anything before the # reloads the application and ends the session.

What you build and what Salaxy provides ​

You buildSalaxy provides
Your product, its header, menu and footerThe payroll UI, kept up to date — new features arrive without work on your side
Your users' sign-inPayroll logic and compliance: tax, insurance, Incomes Register, pensions
Token issuing in your backend (signed JWT → access token)The token endpoint; you create your certificate in the Salaxy web application
The page that hosts the iframe: sizing, loading indicator, session-expiry handlingHosting of the payroll application on test, demo and production hosts
Your navigation choice — Salaxy's built-in menu or your ownYour design implemented in the payroll UI — colours, logo, fonts — from your visual design, as part of the partnership
Optional REST integrations: account creation, payment channel, accounting dataThe REST API and the payroll engine behind it

What you do not do: access the iframe's contents, change Salaxy's internal routing, or implement payroll logic yourself. If you need deep UI changes beyond the design, or control over the payroll components themselves, white label is the wrong fit — use the REST API and build your own UI, or the MCP server for an agent.

How a white label project goes ​

White label project phasesSix phases: agree, test set-up, build, design, integrate (optional), go live.1 Agree2 Test set-up3 Build4 Design5 Integrate6 Go liveTogetherYou · Salaxy helpsYouTogetherYou · optionalTogether
Purple: done together with Salaxy. Grey: your development work. Dashed: optional.
PhaseWhat happensTechnical outcome
1. AgreeCommercial terms (per-payslip pricing), the data processing agreement, scope: which payroll features your users getAgreement; test access
2. Test set-upGet a test account and create your certificate. Embed test-embed.palkkaus.fi with a test token — the five-minute proof of lifeThe payroll UI running inside your page
3. BuildToken issuing in your backend (step 2 above); the hosting page with sizing, loading and session-expiry handling; your navigation choiceYour users reach payroll through your own sign-in
4. DesignYou provide your visual design; Salaxy implements it in the payroll UI (the design, formerly called the skin) — included in the partnership and its integration supportThe payroll UI looks like your product
5. Integrate (optional)REST API integrations: creating accounts from your system, your own payment channel, accounting dataPayroll connected to the rest of your product
6. Go liveProduction checklist: token issuing, token renewal, iframe height, session-expiry UX, final design. Switch to embed.palkkaus.fiLive for your customers

Availability ​

Embedded white label is available in Finland. For other countries it is not yet decided — they launch on MCP and skills.

Technical guides ​

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.